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Section  1:  User  Commands 

Entry  Name(Section):  name  Description 

intro(l)   introduction  to  command  utilities  and  application  programs 

adb(l):    adb  absolute  debugger 

adjust(l):    adjust   simple  text  formatter 

admin(l):    admin   create  and  administer  SCCS  files 

alias:  substitutecommand  and/or  file  name  see  sh-posix(l) 

alias:  substitutecommand  and/or  filename  see  csh(l) 

alias:  substitutecommand  and/or  filename  see  ksh(l) 

alloc:  show  dynamic  memory  usage  seecsh(l) 

answer(l):    answer  phone  message  transcription  system 

ar(l):    ar  maintain  portable  archives  and  libraries 

as(l):    as  assembler  (Precision  Architecture) 

asa(l):    asa   interpret  ASA  carriage  control  characters 

at(l):    at,  batch   execute  batched  commands  immediately  or  at  a  later  time 

attributes(l):    attributes   describe audiofile 

awk(l):    awk   text  pattern  scanning  and  processing  language 

banner(l):   banner   make  posters  in  large  letters 

basename(l):   basename,  dirname  extract  portions  of  path  names 

batch:    execute  batched  commands  immediately  see  at(l) 

bc(l):   be   arbitrary-precision  arithmetic  language 

bdiff(l):   bdiff   diff  for  large  files 

bfs(l):   bfs   big  file  scanner 

break:  exit  from  enclosi ng  for/next  loop  seecsh(l) 

break:  exit  from  enclosing  for/next  loop   see  ksh(l) 

break:  exit  from  enclosi  ng  for/next  loop  see  sh-bourne(l) 

break:  exit  from  enclosing  for/next  loop   see  sh-posix(l) 

breaksw:  break  from  switch  and  resume  after  endsw  see  csh(l) 

bs(l):   bs   a  compiler/interpreter  for  modest-sized  programs 

cal(l):    cai   print  calendar 

calendar(l):    calendar   reminder  service 

cancel:    cancel  requests  on  an  LP  printer  or  plotter   see  lp(l) 

case:  label  in  a  switch  statement  seecsh(l) 

case:  label  in  a  switch  statement   see  ksh(l) 

case:  label  in  a  switch  statement   see sh-posix(l) 

cat(l):    cat   concatenate,  copy,  and  print  files 

ccat:  cat  compacted  files  see  compact(l) 

cc  bundled(l):    cc_bundled  bundled  C  compiler 

cd:  change  working  directory   seecsh(l) 

cd:  change  working  directory  see  ksh(l) 

cd:  change  working  directory   see  sh-bourne(l) 

cd:  change  working  directory  see  sh-posix(l) 

cd(l):    cd  change  working  directory 

cd(l):    command  execute  a  simple  command 

cdc(l):    ede  change  the  delta  commentary  of  an  SCCS  delta 

chacl(l):    chad   add,  modify,  delete,  copy,  or  summarize  access  control  lists  (ACLs)  of  files 

chatr(l):    chatr   change  program's  internal  attributes 

chdir:  change  current  working  directory   see  csh(l) 

checknr(l):    checknr   check  nroff/troff  files 

chfn(l):    chfn   change  user  information  in  password  file;  used  by  finger 

chgrp:  change filegroup   seechown(l) 

chkey(l):  chkey  change  user's  secure  RPC  key 

chmod(l):    chmod   change  file  mode  access  permissions 

chown(l):    chown,  chgrp  change  file  owner  or  group 

chsh(l):    chsh  change  default  login  shell 

ci(l):    ci   check  in  RCS  revisions 

ckconfig(l):    ckconfig  verify  pathnameof  FTP  configuration  files 
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cksum(l):    cksum  print  file  checksum  and  sizes 

clear(l):    clear   clear  terminal  screen 

cmp(l):    cmp   compare  two  files 

co(l):    co   check  out  RCS  revisions 

col(l):    col   filter  reverse  line-feeds  and  backspaces 

comb(l):    comb   combine  sees  deltas 

comm(l):    comm  select  or  reject  lines  common  to  two  sorted  files 

compact(l):    compact,  uncompact,  ccat   compact  and  uncompact  files,  and  cat  them 

compress(l):    compress,  compressdir,  uncompress,  uncompressdir,  zcat           compress  and  expand  data 

compressdir:  compress  files  in  a  directory  see  compress(l) 

continue:  resume  execution  of  nearest  whileor  foreach   seecsh(l) 

continue:  resume  next  iteration  of  enclosing  for/next  loop   see  ksh(l) 

continue:  resume  next  iteration  of  enclosing  for/next  loop  see  sh-bourne(l) 

continue:  resume  next  iteration  of  enclosing  for/next  loop   see  sh-posix(l) 

convert(l):    convert  convert  audio  file 

cp(l):    cp  copy  file,  files,  or  directory  subtree 

cpio(l):    cpio   copy  filearchives  in  and  out 

cpp(l):    cpp   the  C  language  preprocessor 

crontab(l):    crontab  user  crontab  file  operations 

crypt(l):    crypt   encode/decode  files 

csh(l):    csh   a  shell  (command  interpreter)  with  C-l ike  syntax 

csplit(l):    csplit   context  split 

ct(l):    ct  spawn  getty  to  a  remote  terminal  (call  terminal) 

ctags(l):    ctags   create  a  tags  file 

cu(l):    cu  call  another  (UNIX)  system;  terminal  emulator 

cue(l):    cue   HP  Character -Terminal  User  Environment  (CUE) 

cut(l):    cut  cut  out  (extract)  selected  fields  of  each  line  of  a  file 

date(l):    date   display  or  set  the  system-clock  date  and  time 

dc(l):    dc   desk  calculator 

dd(l):    dd   convert,  reblock,  translate,  and  copy  a  (tape)  file 

default:  label  default  in  switch  statement  seecsh(l) 

delta(l):    delta   make  a  delta  (change)  to  an  SCCS  file 

deroff(l):    deroff   remove  nroff,  tbl,  and  neqn  constructs 

diff(l):    dif  f ,  dif  fh   differential  file  comparator 

diff3(l):    diff3   3-way  differential  file  comparison 

diffh:  differential  file  comparator  seediff(l) 

diffmk(l):    diffmk   mark  differences  between  files 

dircmp(l):    dircmp   directory  comparison 

dirname:  extract  portions  of  path  names  see  basename(l) 

dirs:  print  the  directory  stack  seecsh(l) 

disable:    disable  LP  printers   seeenable(l) 

dmpxlt(l):    dmpxit    dump  iconv  translation  tables  to  a  readable  format 

domain name(l):    domainname   set  or  display  NIS  domain  name 

dos2ux(l):    dos2ux,  ux2dos   convert  ASCII  file  format 

doschmod(l):    doschmod   change  attributes  of  a  DOSfile 

doscp(l):    doscp  copy  to  or  from  DOS  files 

dosdf(l):    dosdf   report  number  of  free  disk  clusters 

dosii:  list  contents  of  DOS  directories   seedosls(l) 

dosls(l):    dosis,  dosii   list  contents  of  DOS  directories 

dosmkdir(l):    dosmkdir   make  a  DOS  directory 

dosrm(l):    dosrm,  dosrmdir   remove  DOS  files  or  directories 

dosrmdir:  remove  DOS  directories   seedosrm(l) 

du(l):    du  summarize  disk  usage 

dumpmsg:    extract  messages  from  message  catalog  file   seefindmsg(l) 

echo:  echo  (print)  arguments  see  csh(l) 

echo:  echo  (print)  arguments   see  ksh(l) 

echo:  echo  (print)  arguments  see  sh-bourne(l) 

echo:  echo  (print)  arguments   see  sh-posix(l) 

echo(l):    echo   echo  (print)  arguments 

ed(l):    ed,  red   line-oriented  text  editor 

edit:    extended  line-oriented  text  editor  seeex(l) 
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egrep:    search  a  file  for  a  pattern   see  grep(l) 

elfdump(l):    elf  dump   dump  information  contained  in  object  files 

elm(l):    elm  process  electronic  mail  through  a  screen-oriented  interface 

elmalias(l):    elmaiias  display/verify  elm  user  and  system  aliases 

enabled):    enable,  disable   enable/disable  LP  printers 

end:  termi nate foreach  or  whileloop  seecsh(l) 

endsw:  terminate  switch  statement   seecsh(l) 

env(l):    env   set  environment  for  command  execution 

eucset(l):    eucset   set  and  get  EUC  code  widths  for  Idterm 

eval:  read  arguments  as  shell  input  and  execute  resulting  seecsh(l) 

eval:  read  arguments  as  shell  input  and  execute  resulting  commands  see  ksh(l) 

eval:  read  arguments  as  shell  input  and  execute  resulting  commands  see  sh-bourne(l) 

eval:  read  arguments  as  shell  input  and  execute  resulting  commands  see  sh-posix(l) 

ex(l):    edit,  ex  extended  line-oriented  text  editor 

exec:  execute  command  without  creating  new  process  see  csh(l) 

exec:  execute  command  without  creating  new  process   see  ksh(l) 

exec:  execute  command  without  creating  new  process  see  sh-bourne(l) 

exec:  execute  command  without  creating  new  process   see  sh-posix(l) 

exit:  exit  shell  with  exit  status  seecsh(l) 

exit:  exit  shell  with  exit  status  see  ksh(l) 

exit:  exit  shell  with  exit  status   see sh-bourne(l) 

exit:  exit  shell  with  exit  status  see sh-posix(l) 

expand(l):    expand,  unexpand   expand  tabs  to  spaces,  and  vice  versa 

expand  alias(l):    expand_aiias   recursively  expands  the  sendmail  aliases 

export:  export  variable  names  to  environment  of  subsequent  commands   see  ksh(l) 

export:  export  variable  names  to  environment  of  subsequent  commands  see  sh-bourne(l) 

export:  export  variable  names  to  environment  of  subsequent  commands   see  sh-posix(l) 

expr(l):    expr   evaluate  arguments  as  an  expression 

factor(l):    factor,  primes   factor  a  number,  generate  large  primes 

false:  do  nothing  and  return  non-zero  exit  status  seetrue(l) 

fastbind(l):    fastbind   prepare  an  incomplete  executablefor  faster  program  start-up 

fastmail(l):    fastmaii   quick  batch  mail  interface 

fc:  edit  and  execute  previous  command  see  ksh(l) 

f  c:  edit  and  execute  previous  command  see  sh-posix(l) 

fgrep:    search  a  file  for  a  string  (fast)  see  grep(l) 

file(l):    file  determine  file  type 

find(l):    find   find  files 

findmsg(l):    f  indmsg,  dumpmsg   create  message  catalog  file  for  modification 

findstr(l):    findstr  find  strings  for  inclusion  in  message  catalogs 

finger(l):    finger  user  information  lookup  program 

fmt(l):    fmt   format  text 

fold(l):    fold   fold  long  linesfor  finite  width  output  device 

for:  execute  a  do  list  see  ksh(l) 

for:  execute  a  do  list  see  sh-posix(l) 

forder(l):    f  order   convert  file  data  order 

foreach:  initiaterepetitive loop  seecsh(l) 

from(l):    from  who  is  my  mail  from? 

fruled(l):    fruled  turn  on/off  attention  LEDs 

ftio(l):    ftio  faster  tape  I/O 

ftp(l):    ftp   file  transfer  program 

ftpaccess(l):    ftpaccess   create  shutdown  message  files  to  shutdown  ftp  servers 

ftpcount(l):    ftpcount   show  current  number  of  users  for  each  ftp  class 

ftprestart(l):    ftprestart  remove  the  shutdown  message  files  created  byftpshut 

ftpwho(l):    ftpwho   show  process  information  on  each  ftp  user 

gencat(l):    gencat  generate  a  formatted  message  catalog  file 

genxlt(l):    genxit   generate  iconv  translation 

get(l):    get   get  a  version  of  an  SCCS  file 

getaccess(l):    getaccess   list  access  rights  to  file(s) 

getacl(l):    getaci  list  access  control  lists  for  files,  J  FSonly 

getconf(l):    getconf   get  POSIX  configuration  values 

getopt(l):    getopt   parse  command  options 
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getopts(l):    getopts  parse  utility  (command)  options 

getprivgrp(l):    getprivgrp   get  special  attri butes for  group 

glob:  echo  without  A  \ '  escapes   see  csh(l) 

goto:  continue  execution  on  specified  line  seecsh(l) 

gprof(l):    gprof   display  call  graph  profile  data 

grep(l):    grep,  egrep,  f  grep   search  a  file  for  a  pattern 

grget:  get  password  and  group  information  see  pwget(l) 

groups(l):    groups   show  group  memberships 

hash:  remember  command  location  in  search  path  see sh-bourne(l) 

hashcheck:    create  hash  codes  from  compressed  spelling  list   seespell(l) 

hashmake:    convert  words  to  9-digit  hashcodes  see  spell(l) 

hashstat:  print  hash  tableeffectiveness  statistics   seecsh(l) 

head(l):    head  print  first  few  lines  in  a  file 

history:  display  event  history  list   seecsh(l) 

hostname(l):    hostname  set  or  display  name  of  current  host  system 

hp(l):    hp   handlespecial  functions  of  hp  2640and  hp  2621-seriesterminals 

hp-mc680x0:  provide  truth  value  about  processor  type  see  machid(l) 

hp-pa:  provide  truth  value  about  processor  type  see  machid(l) 

hp9000s200:  provide  truth  value  about  processor  type  see  machid(l) 

hp9000s300:  provide  truth  value  about  processor  type  see  machid(l) 

hp9000s500:  provide  truth  value  about  processor  type  see  machid(l) 

hp9000s800:  provide  truth  value  about  processor  type  see  machid(l) 

hyphen(l):    hyphen   find  hyphenated  words 

iconv(l):    iconv  character  code  set  conversion 

id(l):    id  print  user  and  group  I  Ds  and  names 

ident(l):    ident   identify  files  in  RCS 

idlookup(l):    idiookup   identify  the  user  of  a  particular  TCP  connection 

ied(l):    ied  input  editor  and  command  history  for  interactive  programs 

if:  execute  command  if  expression  evaluates  true  seecsh(l) 

if:  execute  command  if  previous  command  returns  exit  status  0  see  ksh(l) 

if:  execute  command  if  previous  command  returns  exit  status  0  see  sh-posix(l) 

insertmsg(l):    insertmsg   use findstr(l)  output  to  insert  calls  to  catgets(3C) 

inv:  make  unprintable  and  non-ASCII  characters  in  a  file  invisible  see  vis(l) 

iostat(l):    iostat   report  I/O  statistics 

ipcrm(l):    ipcrm   remove  a  message  queue,  semaphore  set  or  shared  memory  id 

ipcs(l):    ipcs   report  status  of  interprocess  communication  facilities 

jobs:  list  active  jobs   seecsh(l) 

jobs:  list  active  jobs  see  ksh(l) 

jobs:  list  active  jobs  see  sh-posix(l) 

join(l):    join   relational  database  operator 

kdestroy(l):    kdestroy   destroy  Kerberos  tickets 

kermit(l):    kermit  communication  software  for  serial  and  network  connections 

keylogin(l):    keyiogin  decrypt  and  store  secret  key 

keylogout(l):    keyiogout   delete  secret  key  stored  with  keyserv 

keysh(l):    keysh   context-sensitive  softkey  shel  I 

kill:  send  termination  or  specified  signal  toa  process   seecsh(l) 

kill:  terminatejob  or  process  see  ksh(l) 

kill:  terminatejob  or  process  see  sh-posix(l) 

kill(l):    kill   send  a  signal  toa  process;  terminate  a  process 

kinit(l):    kinit   obtain  and  cache  Kerberos  ticket-granting  ticket 

klist(l):    klist   list  cached  Kerberos  tickets 

kpasswd(l):    kpasswd  change  a  user's  Kerberos  password 

ksh(l):    ksh,  rksh  shell,  the  standard/restricted  command  programming  language 

ktutil(l):    ktutii   Kerberos  keytab  file  maintenance  utility 

kvno(l):    kvno   print  key  version  numbers  of  Kerberos  principals 

l:  list  contents  of  directories   see  ls(l) 

last(l):    last,  lastb  indicate  last  logins  of  users  and  ttys 

lastb:    indicate  last  bad  logins  of  users  and  ttys   seelast(l) 

lastcomm(l):    lastoomm  show  last  commands  executed  in  reverse  order 

lc:  list  contents  of  directories   see  ls(l) 

ld(l):    id  link  editor 
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ldd(l):    ldd  list  dynamic  dependencies  of  executable  files  or  shared  libraries 

leave(l):    leave  remind  you  when  you  have  to  leave 

let:  evaluatearithmeticexpression   seeksh(l) 

let:  evaluatearithmeticexpression   see sh-posix(l) 

iibiu62.a:    IBM  APPC  (Advanced  Program-to-Program  Communications)  API   seesna(l) 

lifcp(l):    lif  cp   copy  to  or  from  LI  F  files 

lifinit(l):    lif init  write  LIF  volume  header  on  file 

lifls(l):    lif  is   list  contents  of  a  LI  F  directory 

lifrename(l):    lif  rename  rename  LIF  files 

lifrm(l):    lifrm  remove  a  LIF  file 

limit:  limit  usage  by  current  process  seecsh(l) 

line(l):    line  read  one  line  from  user  input 

Mstusers(lM):    listusers   display  user  login  data 

li:  list  contents  of  directories   see  ls(l) 

ln(l):    in  link  files  and  directories 

locale(l):    locale   get  locale-specific  (NLS)  information 

lock(l):    lock  reserve  a  terminal 

logger(l):    logger   make  entries  in  the  system  log 

login:  terminate  login  shell   seecsh(l) 

login(l):    login   sign  on;  start  terminal  session 

logname(l):    logname   get  login  name 

logout:  terminate  login  shell   seecsh(l) 

lorder(l):    lorder   find  ordering  relation  for  an  object  library 

lp(l):    cancel,  lp,  lpait   print/alter/cancel  requests  on  an  LP  printer  or  plotter 

lpait:    alter  requests  on  an  LP  printer  or  plotter   see  lp(l) 

Ipfilter(l):    lpfiiter   filters  used  by  the  lp  interface  scripts 

Ipstat(l):    lpstat   print  LP  status  information 

ls(l):    is,  1,  lc,  11,  lsf,  lsr,  lsx  list  contents  of  directories 

Isacl(l):    lsaci   list  access  control  lists  (acls)  of  files 

lsf:  list  contents  of  directories   see  ls(l) 

lsr:  list  contents  of  directories   see  ls(l) 

lsx:  list  contents  of  directories   see  ls(l) 

m4(l):   m4   macro  processor 

machid(l):     hp9000s200,  hp9000s300,  hp9000s500,  hp9000s800, 

pdpii,  u3b,  u3b5,  vax  provide  truth  valueabout  processor  type 

mail(l):   mail,  rmaii  send  mail  to  users  or  read  mail 

mailfrom(l):   maiifrom  summarize  mail  folders  by  subject  and  sender 

mailq(l):    mailq   prints  the  mail  queue 

mailstats(l):   maiistats   print  mail  traffic  statistics 

mailx(l):   maiix   interactive  message  processing  system 

make(l):   make   maintain,  update,  and  regenerate  groups  of  programs 

makekey(l):   makekey  generate  encryption  key 

man(l):   man  find  manual  information  by  keywords;  print  out  a  manual  entry 

mediainit(l):   mediainit   initializedisk  or  cartridge tapemedia,  partition  dds  tape 

merge(l):   merge  three-way  file  merge 

mesg(l):   mesg  permit  or  deny  messages  to  terminal 

mkdir(l):   mkdir  make  a  directory 

mkfifo(l):   mkfifo  make  FIFO  (named  pipe)  special  files 

mkmf(l):   mkmf   make  a  makefile 

mkmsgs(l):   mkmsgs   create  message  files  for  use  by  gettxtQ 

mkstr(l):   mkstr  extract  error  messages  from  C  source  into  a  file 

mktemp(l):   mktemp   make  a  name  for  a  temporary  file 

mkuupath:  manage  the  pathali as  database  seeuupath(l) 

mm(l):   mm,  osdd  print/check  documents  formatted  with  the  mm  macros 

model  (1):   model   print  name  of  current  HP-UX  version 

more(l):   more,  page   file  perusal  filter  for  crt  viewing 

mpsched(l):   mpsched  control  processor  or  locality  domain  on  which  a  specific  process  executes 

mt(l):   mt   magnetic  tape  manipulating  program 

mv(l):   mv  move  or  rename  files  and  directories 

neqn(l):    neqn   format  mathematical  text  for  nroff 

netstat(l):    netstat   show  network  status 
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newalias(l):    newaiias   install  new  elm  aliases  for  user  or  system 

newform(l):    newform  change  or  reformat  a  text  file 

newgrp:  equivalent  to  exec  newgrp  see  sh-bourne(l) 

newgrp:  equivalent  to  exec  newgrp    seecsh(l) 

newgrp:  equivalent  to  exec  newgrp   see  ksh(l) 

newgrp:  equivalent  to  exec  newgrp   see  sh-posix(l) 

newgrp(l):    newgrp   switch  to  a  new  group 

newmail(l):    newmaii   notify  users  of  new  mail  in  mailboxes 

news(l):    news   print  news  items 

nice:  alter  command  priority   seecsh(l) 

nice(l):    nice  run  a  command  at  nondefault  priority 

nis-Kl):    nis+  new  version  of  the  network  information  name  service. 

niscat(l):    niscat  display  Nl S+tables  and  objects 

nischgrp(l):    nischgrp   change  the  group  owner  of  an  N I S+ object 

nischmod(l):    nischmod  change  access  rights  on  an  N I S+ object 

nischown(l):    nischown  change  the  owner  of  an  N I S+ object 

nischttl(l):    nischtti  change  the  time  to  livevalueof  an  NIS+object 

nisdefaults(l):    nisdefaults   display  NIS+default  values 

niserror(l):    niserror   display  N I S+ error  messages 

nisgrep(l):    nisgrep   utility  for  searching  NIS+tables 

nisgrpadm(l):    nisgrpadm   administer  NIS+groups 

nisln(l):    nisin   symbolically  link  Nl  S+objects 

nisls(l):    nisis  list  the  contents  of  an  Nl  S+directory 

nismatch(l):    nismatch  utility  for  searching  NIS+tables 

nismkdir(l):    nismkdir  create  N I S+  directories 

nispasswd(l):    nispasswd  change  N I S+  password  information 

nisrm(l):    nisrm  remove  N I S+ objects  from  the  namespace 

nisrmdir(l):    nisrmdir   remove  NIS+directories 

nistbladm(l):    nistbiadm  admi nister  N I S+ tables 

nistest(l):    nistest   return  thestateof  theNIS+namespaceusinga  conditional  expression 

nl(l):    nl   line  numbering  filter 

nljust(l):    nl  just  justify  lines,  left  or  right,  for  printing 

nm(l):    nm   print  name  list  of  common  object  file 

nohup:  ignore  hangups  during  command  execution  seecsh(l) 

nohup(l):    nohup   run  a  command  immune  to  hangups 

notify:  notify  user  of  change  in  job  status  seecsh(l) 

nroff(l):    nrof  f   format  text 

nslookup(l):    nsiookup  query  name  servers  interactively 

nsquery(l):    nsquery  query  the  Name  Service  Switch  backend  libraries 

od(l):    od,  xd   octal  and  hexadecimal  dump 

odump(l):    odump  dump  information  contained  in  SOM  object  files 

on(l):    on  execute  a  command  on  a  remote  host;  environment  similar  to  local  environment 

onintr:  specify  shell's  treatment  of  interrupts   see  csh(l) 

osdd:    print/check  documents  formatted  with  the  mm  macros  see  mm(l) 

pack(l):   pack,  peat,  unpack  compress  and  expand  files 

page:  file  perusal  filter  for  crt  viewing  see  more(l) 

parstatus(l):   parstatus   display  information  about  the  Superdome  complex 

partition(l):   partition   display  information  about  Superdome  commands 

passwd(l):   passwd   change  login  password  and  associated  attributes 

paste(l):   paste  merge  same  lines  of  several  files  or  subsequent  lines  of  one  file 

patch(l):   patch   applying  a  diff  file  to  an  original 

pathalias(l):   pathaiias   electronic  address  router 

pathchk(l):   pathchk   check  path  names 

pax(l):   pax  portable  archive  exchange 

peat:  compress  and  expand  files  see  pack(l) 

pdclean(l):   pdciean  remove  jobs  from  specified  object 

pdcreate(l):   pdcreate   creates  print  objects 

pddelete(l):   pddeiete   deletes  print  objects 

pddisable(l):   pddisabie   stops  printers  from  accepting  jobs  and  logs  from  logging 

pdenable(l):   pdenabie  enables  printers  to  accept  jobs  and  logs  to  log 

pdls(l):   pdis   lists  selected  attribute  values 
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pdmod(l):   pdmod  modifies  attributes  of  submitted  print  jobs 

pdmsg(l):   pdmsg  displays  the  text  and  description  of  a  HPDPS  message  at  the  command  line 

pdpii:  provide  truth  value  about  processor  type  see  machid(l) 

pdpause(l):   pdpause   pausesjobs,  physical  printers,  servers,  or  queues 

pdpr(l):   pdpr   submits  print  jobs 

pd promoted):   pdpromote   advances  a  job  to  the  top  of  a  queue 

pdq(l):   pdq   queriesand  lists  the  status  of  oneor  more  print  jobs 

pdresubmit(l):   pdresubmit   resubmits  previously  submitted  print  jobs 

pdresume(l):   pdresume   enables  paused  objects  to  resume  operation 

pdrm(l):   pdrm   removes  print  jobs 

pdset(l):   pdset   modifies  attributes  of  submitted  print  jobs 

pdshutdown(l):   pdshutdown   stop  servers 

pg(l):   pg  file  perusal  filter  for  soft-copy  terminals 

popd:  pop  directory  stack  see  csh(l) 

pppd(l):   pppd   point  to  point  protocal  daemon 

pr(l):   pr   format  and  print  files 

praliases(l):   praiiases  print  system-wide sendmail  aliases 

prealloc(l):   preaiioc  preal  locate  disk  storage 

primes:  generate  large  prime  numbers  seefactor(l) 

print:  output  from  shell   see  ksh(l) 

print:  output  from  shell   see  sh-posix(l) 

printenv(l):   printenv  print  out  the  environment 

printf(l):    echo  print  formatted  arguments 

prmail(l):   prmaii   print  out  mail  in  the  incoming  mailbox  file 

prof(l):   prof  display  profile  data 

prs(l):   prs   print  and  summarize  an  sees  file 

ps(l):   ps   report  process  status 

ptx(l):   ptx   permuted  index 

pty:  get  the  name  of  the  pseudo-terminal   seetty(l) 

pushd:  push  directory  stack  seecsh(l) 

pwd:  print  current  working  directory   see  ksh(l) 

pwd:  print  current  working  directory   see  sh-posix(l) 

pwd:  working  directory  name   see  sh-bourne(l) 

pwd(l):   pwd  working  directory  name 

pwget(l):   pwget,  grget   get  password  and  group  information 

quota(l):    quota  display  disk  usage  and  limits 

ranlib(l):    ranlib   regenerate  archive  symbol  table 

rcp(l):    rep   remote  file  copy 

rcp(l):    rep   remote  file  copy 

rcs(l):    res   change  RCS  file  attributes 

rcsdiff(l):    rcsdiff   compare  RCS  revisions 

rcsmerge(l):    rcsmerge   merge  RCS  revisions 

rdist(l):    rdist   remote  file  distribution 

read:  input  and  parse  a  line  see  ksh(l) 

read:  input  and  parsea  line  see sh-posix(l) 

read:  read  line  from  standard  input  see  sh-bourne(l) 

read(l):    read  read  a  line  from  standard  input 

readmail(l):    readmaii   read  mail  from  a  mail  folder  or  incoming  mailbox 

readonly:  mark  name  as  read-only  see  sh-bourne(l) 

readonly:  mark  names  as  unredefinable  see  ksh(l) 

readonly:  mark  names  as  unredefinable  see  sh-posix(l) 

red:    restricted  line-oriented  text  editor  seeed(l) 

rehash:  recompute  internal  hash  table  see  csh(l) 

remsh(l):    remsh  execute  from  a  remote  shell 

repeat:  execute  command  more  than  once  see  csh(l) 

return:  exit  function  with  return  value  see  sh-bourne(l) 

return:  shell  function  return  to  invoking  script   see  ksh(l) 

return:  shell  function  return  to  i nvoki ng  scri pt   see sh-posix(l) 

rev(l):    rev  reverse  lines  of  a  file 

rksh:  restricted  Korn  shell  command  programming  language  seeksh(l) 

rlog(l):    rlog  print  log  messages  and  other  information  on  RCS  files 
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rlogin(l):    riogin   remote  login 

rm(l):    rm   remove  files  or  directories 

rmaii:  send  mail  to  users  or  read  mail   see  mail(l) 

rmdel(l):    rmdei  remove  a  delta  from  an  sees  file 

rmdir(l):    rmdir   remove  directories 

rmnl(l):    rmni   remove  extra  new-line  characters  from  file 

rpcgen(l):    rpegen   an  RPC  protocol  compiler 

rsh:  restricted  shell  command  programming  language  see sh-bourne(l) 

rtprio(l):    rtprio   execute  process  with  real-time  priority 

rtsched(l):    rtsched  execute  process  with  POSIX  real-time  priority 

rup(l):  rup   show  host  status  of  local  machines  (RPC  version) 

ruptime(l):    ruptime  show  status  of  local  machines 

rusers(l):  rusers  determine  who  is  logged  onto  machines  on  the  local  network 

rwho(l):    rwho  show  who  is  logged  in  on  local  machines 

sact(l):    sact  print  current  sees  file  editing  activity 

samlogviewer(l):    samiog_viewer   tool  for  viewing  and  saving  the  SAM  logfile 

sccs(l):    sees   utility  program  for  SCCS  commands 

sccsdiff(l):    sccsdiff   compare  two  versions  of  an  sees  file 

sccshelp(l):    sccshelp   help  for  SCCS  commands 

script(l):    script   make  typescript  of  terminal  session 

sdiff(l):    sdiff  side-by-sidedifference  program 

sed(l):    sed  stream  text  editor 

send  sound(l):    send_sound   play  audiofile 

serialized):    serialize   force  target  process  to  run  serially  with  other  processes 

set:  set/define  flags  and  arguments   seecsh(l) 

set:  set/define  options  and  arguments  see  ksh(l) 

set:  set/define  options  and  arguments   see  sh-bourne(l) 

set:  set/define  options  and  arguments  see  sh-posix(l) 

setacl(l):    setaci   modify  access  control  lists  for  files  (J  FS  only) 

setenv:  define  environment  variable  seecsh(l) 

sh(l):    sh  overview  of  various  system  shells 

sh-bourne(l):    sh,  rsh   shell,  the  standard/restricted  command  programming  language 

sh-posix(l):    sh  shell,  the  standard/restricted  command  programming  language 

shar(l):    shar   make  a  shell  archive  package 

shift:  shift  argv  members  one  position  to  left  see  csh(l) 

shift:  shift  argv  members  one  position  to  left   see  ksh(l) 

shift:  shift  argv  members  one  position  to  left   see  sh-posix(l) 

shift:  shift  positional  parameters  to  next  lower  position  see  sh-bourne(l) 

shl(l):    shi  shell  layer  manager 

size(l):    size   print  section  sizes  of  object  files 

sleep(l):    sleep   suspend  execution  for  an  interval 

slp(l):    sip  set  printing  options  for  a  non-serial  printer 

sna(l):    sna3l79g,  sna3270,  sna3770   IBM  3179G/3192G,  3270,  3777 terminal  emulator 

soelim(l):    soelim  eliminate .so's from  nroff  input 

sort(l):    sort   sort  or  merge  files 

source:  define  source  for  command  input  seecsh(l) 

spell(l):     spell,  hashmake,  spellin,  hashcheck   find  spelling  errors 

speilin:    create  compressed  spelling  list  from  hash  codes   see  spell(l) 

split(l):    split   split  a  file  into  pieces 

ssp(l):    ssp   remove  multipleline-feedsfrom  output 

strings(l):    strings   find  the  printablestrings  in  an  object  or  other  binary  file 

strip(l):    strip  strip  symbol  and  line  number  information  from  an  object  file 

stty(l):    stty   set  the  options  for  a  terminal  port 

su(l):    su  switch  user 

sum(l):    sum   print  checksum  and  block  count  of  a  file 

switch:  define  switch  statement   seecsh(l) 

tabs(l):    tabs   set  tabs  on  a  terminal 

tail(l):    tail  deliver  the  last  part  of  a  file 

talk(l):    talk  talk  to  another  user 

tar(l):    tar  tapefilearchiver 

tbl(l):    tbi   format  tables  for  nroff 
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tee(l):    tee   pipe  fitting 

telnet(l):    telnet   user  interface  to  the  telnet  protocol 

test:  evaluate  conditional  expression   seecsh(l) 

test:  evaluate  conditional  expression  see  ksh(l) 

test:  evaluate  conditional  expression  see  sh-posix(l) 

test(l):    test   condition  evaluation  command 

tftp(l):    tftp   trivial  file  transfer  program 

time,  times:  print  summary  of  time  used  by  processes  see  ksh(l) 

time:  print  accumulated  shell  and  children  process  times  see  sh-bourne(l) 

time:  print  summary  of  time  used  by  shell  and  children   seecsh(l) 

time(l):    time   time  a  command 

time,  times:  print  summary  of  time  used  by  processes  see  sh-posix(l) 

times:  print  accumulated  user  and  system  process  times   see  sh-bourne(l) 

timex(l):    timex   time  a  command;  report  process  data  and  system  activity 

top(l):    top   display  and  update  information  about  top  processes  on  system 

touch(l):    touch  update  access,  modification,  and/or  change  times  of  file 

tput(l):    tput   query  termi  nfo  database 

tr(l):    tr   translate  characters 

trap:  execute  command  upon  receipt  of  signal  see  sh-bourne(l) 

trap:  trap  specified  signal   see  ksh(l) 

trap:  trap  specified  signal   see  sh-posix(l) 

true(l):    true,  false  return  zero  or  non-zero  exit  status 

tset(l):    tset   terminal -dependent  initialization 

tsm(l):    tsm  Terminal  Session  Manager 

tsm.command(l):    tsm.  command  send  commands  to  Terminal  Session  Manager 

tsm.info(l):    tsm.  info  get  Terminal  Session  Manager  state  information 

tsort(l):    tsort  topological  sort 

tty(l):    tty,  pty   get  the  name  of  the  terminal 

ttytype(l):    ttytype   terminal  identification  program 

type:  show  interpretation  of  name  as  if  a  command  see  sh-bourne(l) 

typeset:  control  leading  blanks  and  parameter  handling   see  ksh(l) 

typeset:  control  leading  blanks  and  parameter  handling   see  sh-posix(l) 

u370:  provide  truth  value  about  processor  type  see  machid(l) 

u3b:  provide  truth  value  about  processor  type  see  machid(l) 

u3bi0:  provide  truth  value  about  processor  type  see  machid(l) 

u3b2:  provide  truth  valueabout  processor  type  see  machid(l) 

u3b5:  provide  truth  valueabout  processor  type  see  machid(l) 

ul(l):    ui   do  underlining 

ulimit:  impose  file  size  limit  for  child  processes  see  sh-bourne(l) 

ulimit:  set  size  or  time  limits  see  ksh(l) 

ulimit:  set  size  or  time  limits  see  sh-posix(l) 

umask:  set  permissions  mask  for  creating  new  files  seecsh(l) 

umask:  set  permissions  mask  for  creating  new  files   see  ksh(l) 

umask:  set  permissions  mask  for  creating  new  files  see  sh-bourne(l) 

umask:  set  permissions  mask  for  creating  new  files   see  sh-posix(l) 

umask(l):    umask  set  file-creation  mode  mask 

umodem(l):    umodem  XMODEM-protocol  file  transfer  program 

unaiias:  discard  specified  alias  seecsh(l) 

unaiias:  discard  specified  alias   see  ksh(l) 

unaiias:  discard  specified  alias   see  sh-posix(l) 

uname(l):    uname  display  information  about  computer  system;  set  node  name  (system  name) 

uncompact:  uncompact  files  see  compact(l) 

uncompress:  expand  compressed  data  see  compress(l) 

uncompressdir:  expand  compressed  files  in  a  directory  see  compress(l) 

unexpand:    convert  spaces  to  tabs  seeexpand(l) 

unget(l):    unget   undo  a  previous  get  of  an  sees  file 

unhash:  disable  use  of  internal  hash  tables  seecsh(l) 

unifdef(l):    unifdef  remove  preprocessor  lines 

uniq(l):    uniq  report  repeated  lines  in  a  file 

units(l):    units   conversion  program 

unpack:  compress  and  expand  files  see  pack(l) 
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unset:  remove  definition/setting  of  flags  and  arguments  see  csh(l) 

unset:  remove  definition/setting  of  options  and  arguments   see  ksh(l) 

unset:  remove  definition/setting  of  options  and  arguments  see  sh-bourne(l) 

unset:  remove  definition/setting  of  options  and  arguments   see  sh-posix(l) 

unsetenv:  remove  variablefrom  environment   seecsh(l) 

until:  execute  commands  until  expression  is  non-zero   see  ksh(l) 

until:  execute  commands  until  expression  is  nonzero   see  sh-posix(l) 

uptime(l):    uptime,  w   show  how  long  system  has  been  up 

users(l):    users  compact  list  of  users  who  are  on  the  system 

uucp(l):    uuop,  uulog,  uuname,  uutry    UNIX  system  to  U N I X  system  copy 

uudeoode:  decode  a  file  encoded  by  uuencode   see  uuencode(l) 

uuencode(l):    uuencode,  uudecode  encode/decode  a  binary  filefor  transmission  by  mailer 

uulog:  access  UUCP  summary  logs   see  uucp(l) 

uuname:  list  known  UUCP  systems  seeuucp(l) 

uupath(l):    uupath,  mkuupath  access  and  manage  the  pathali  as  database 

uupick:  accept  or  reject  incoming  UUCP  messages  see  uuto(l) 

uustat(l):    uustat   uucpstatusinquiryandjobcontrol 

uuto(l):    uuto,  uupick   publicUNix  system  toUNix  system  file  copy 

uutry:  test  for  successful  login  to  remote  system  see  uucp(l) 

uux(l):    uux  UNIX  system  to  UNIX  system  command  execution 

ux2dos:  convert  ASCII  fileformat   see dos2ux(l) 

vacation(l):    vacation  return  "I  am  not  here"  indication 

val(l):   vai   validate SCCS  file 

vax:  provide  truth  value  about  processor  type  see  machid(l) 

vc(l):   vc  version  control 

vedit:    beginner's  screen-oriented  text  editor  see  vi(l) 

vi(l):   vedit,  vi,  view   extended  screen-oriented  text  editor 

view:    read-only  screen-oriented  text  editor  see  vi(l) 

vis(l):   vis,  inv   make  unprintableand  non-ASCI I  characters  in  a  file  visibleor  invisible 

vmstat(l):   vmstat   report  virtual  memory  statistics 

vt(l):   vt   log  in  on  another  system  over  Ian 

wait:  wait  for  background  processes  see  csh(l) 

wait:  wait  for  child  process   see  ksh(l) 

wait:  wait  for  child  process   see  sh-posix(l) 

wait:  wait  for  process  and  report  termination  status  see  sh-bourne(l) 

wait(l):    wait   await  completion  of  process 

wc(l):   wc   count  words,  lines,  and  bytes  or  characters  in  a  file 

what(l):    what  get  SCCS  identification  information 

whence:  define  interpretation  of  name  as  a  command  see  ksh(l) 

whence:  define  interpretation  of  name  as  a  command  see  sh-posix(l) 

whereis(l):    whereis   locate  source,  binary,  and/or  manual  for  program 

which(l):    which   locate  a  program  file  including  aliases  and  paths 

while:  execute  commands  while  expression  is  non-zero  seecsh(l) 

while:  execute  commands  while  expression  is  non-zero   see  ksh(l) 

while:  execute  commands  while  expression  isnonzero   see  sh-posix(l) 

who(l):    who  who  is  currently  logged  in  on  the  system 

whoami(l):    whoami   print  effective  current  user  id 

whois(l):    whois   Internet  user  name  directory  service 

write(l):    write  interactively  write  (talk)  to  another  user 

xargs(l):    xargs  construct  argument  list(s)  and  execute  command 

xd:  hexadecimal  dump  seeod(l) 

xstr(l):    xstr   extract  strings  from  C  programs  to  implement  shared  strings 

yes(l):    yes  be  repetitively  affirmative 

ypcat(l):  ypcat   print  all  Network  I  nformation  Service  map  values 

ypmatch(l):  ypmatch   print  values  of  selected  keys  in  Network  I  nformation  Service  map 

yppasswd(l):    yppasswd  changelogin  password  in  Network  Information  System  (NIS) 

ypwhich(l):    ypwhich  list  Network  I  nformation  System  server  or  map  master 

zcat:  expand  and  cat  data  see  compress(l) 
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NAME 

I  ntroduction  -  an  introduction  to  the  HP-UX  operating  system  and  the  HP-UX  Reference 
INTRODUCTION 

HP-UX  is  the  Hewlett-Packard  Company's  implementation  of  an  operating  system  that  is  compatible  with 
various  industry  standards.  It  is  based  on  the  UNIX®  System  V  Release  4  operating  system  and  includes 
important  features  from  the  Fourth  Berkeley  Software  Distribution. 

Improvements  include  enhanced  capabilities  and  other  features,  developed  by  HP  to  make  HP-UX  a  very 
powerful,  useful,  and  reliable  operating  system,  capable  of  supporting  a  wide  range  of  applications  ranging 
from  simpletext  processing  to  sophisticated  engineering  graphics  and  design.  It  can  readily  be  used  to  con- 
trol instruments  and  other  peripheral  devices.  Real-time  capabilities  further  expand  the  flexibility  of  HP- 
UX  as  a  powerful  tool  for  solving  tough  problems  in  design,  manufacturing,  business,  and  other  areas  where 
responsiveness  and  performance  are  important. 

Extensive  international  language  support  enables  HP-UX  to  interact  with  users  in  any  of  dozens  of  human 
languages.  HP-UX  interfaces  easily  with  local  area  networks  and  resource-sharing  facilities.  By  using 
industry-standard  protocols,  HP-UX  provides  flexible  interaction  with  other  computers  and  operating  sys- 
tems. Optional  software  products  extend  HP-UX  capabilitiesintoa  broad  range  of  specialized  needs. 

The  HP-UX  Reference  is  not  a  learning  tool  for  beginners.  It  is  primarily  a  reference  tool  that  is  most  use- 
ful for  experienced  users  of  UNIX  or  UNIX-like  systems.  If  you  are  not  already  familiar  with  UNIX  or  HP- 
UX,  refer  to  the  series  of  Beginner's  Guides,  tutorial  manuals,  and  other  learning  documents  supplied  with 
your  system  or  avail  able  separately.  System  implementation  and  maintenance  details  are  explained  in  the 
Managing  Systems  and  Workgroups  manual. 

MANPAGE  ORGANIZATION 

The  contents  of  the  HP-UX  Reference  and  its  on-line  counterpart  are  a  number  of  independent  entries 
called  manpages.  These  are  also  called  manual  entries  or  reference  pages. 

For  convenient  reference,  the  manpages  are  divided  into  eight  specialized  sections.  The  printed  manual 
also  has  a  tableof  contents  for  each  volume  and  a  composite  index. 

Each  manpage  consists  of  one  or  more  printed  pages,  with  the  manpage  name  and  section  number  printed 
in  the  upper  corners.  Manpages  are  arranged  alphabetically  within  each  section  of  the  reference,  except  for 
the  intro  page  at  the  beginning  of  each  section.  Manpages  are  referred  to  by  name  and  section  number,  in 
the  form  pagename(section). 

The  manpages  are  avail  able  on-line  through  the  man  command  if  the  manpages  are  present  on  the  system. 
Refer  to  the  man(l)  manpage  in  Section  1  for  more  information. 

Each  page  in  the  printed  manual  has  two  page  numbers,  printed  at  the  bottom  of  the  page.  The  center 
page  number  starts  over  with  page  1  at  the  beginning  of  each  new  manpage;  it  is  placed  between  two 
dashes  in  normal  typeface.  The  number  printed  at  the  outside  corner  on  each  page  sequences  the  printed 
pages  within  a  section.  Users  usually  locate  manpages  by  the  alphabetic  headings  at  the  top  of  the  page  as 
when  reading  a  dictionary. 

Some  manpages  describe  two  or  more  commands  or  routines.  I  n  such  cases,  the  manpage  is  usually  named 
for  the  first  command  or  function  that  appears  in  the  NAME  section.  Occasionally,  a  manpage  name 
appears  as  a  prefix  to  the  NAME  section.  I  n  such  instances,  the  name  describes  the  commands  or  functions 
in  more  general  terms.  For  example,  theacct(lM)  manpage  describes  the  acctdisk,  acctdusg,  acc- 
ton,  and  acctwtmp  commands,  whilethe  string(3C)  manpage  describes  many  character  string  functions. 

The  various  sections  are  described  as  follows: 

Volume  Table  of  Contents  (Printed  Manual) 

A  complete  listing  of  all  manpages  in  the  order  they  appear  in  each  section,  as  well  as  alphabetically 
intermixed  lists  of  all  command,  function,  and  feature  names  that  are  the  different  from  the  manpage 
where  they  appear 

Section  1:  User  Commands 

Programs  that  are  usually  invoked  directly  by  users  or  from  command  language  procedures  (scripts). 

Section  1M:  System  Administration  Commands 

Commands  used  for  system  installation  and  maintenance,  including  boot  processes,  crash  recovery, 
system  integrity  testing,  and  other  needs.  Most  commands  in  this  section  require  the  superuser 
privilege. 
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Section  2:  System  Calls 

Entries  into  the  HP-UX  kernel,  including  the  C-language  interface.  These  topics  are  primarily  of 
interest  to  programmers. 

Section  3:  Library  Functions 

Available  subroutines  that  reside  (in  binary  form)  in  various  system  libraries.  These  topics  are  pri- 
marily of  interest  to  programmers. 

Section  4:  File  Formats 

The  structure  of  various  types  of  files,  primarily  of  interest  to  administrators  and  programmers.  For 
example,  the  link  editor  output  file  format  is  described  in  a. out  (4).  Files  that  are  used  only  by  a  single 
command  (such  as  intermediate  files  used  by  assemblers)  are  not  described.  C-language  declarations 
corresponding  to  the  formats  in  Section  4  can  be  found  in  the  directories  /usr/include  and 
/usr/ include/ sys. 

Section  5:  Miscellaneous 

A  variety  of  information,  such  as  descriptions  of  header  files,  character  sets,  macro  packages,  and 
other  topics. 

Section  7:  Device  Special  Files 

The  characteristics  of  special  (device)  files  that  provide  the  link  between  HP-UX  and  system  I/O  dev- 
ices. The  names  for  each  topic  usually  refer  to  the  type  of  I/O  device  rather  than  to  the  names  of  indi- 
vidual special  files. 

Section  9:  Introduction  and  Glossary 

A  general  introduction  (this  one)  and  definitions  of  terms  used  in  the  HP-UX  environment. 

Composite  Index  (Printed  Manual) 

An  alphabetical  listing  of  keywords  and  topics  based  on  the  NAME  section  near  the  beginning  of  each 
manpage  as  well  as  other  information,  cross-referenced  to  manpage  names  and  sections.  The  index 
also  contains  references  to  built-in  features  in  the  various  command  interpreters  ("shells"). 

MANPAGE  FORMATS 

All  manpages  follow  an  established  section  heading  format,  but  not  all  section  headings  are  included  in  each 
manpage.  A  few  manpages  have  self-explanatory  specialized  headings. 

NAME 

Gives  the  names  of  the  commands,  functions,  or  features  and  briefly  states  the  purpose. 
SYNOPSIS 

Summarizes  the  syntax  of  the  command  or  program  entity.  A  few  conventions  are  used: 

Constant -width  characters  indicate  literal  characters  that  should  be  entered  exactly  as  they 
appear.  These  characters  appear  in  bold  in  the  online  manpages. 

Italic  strings  represent  variable  elements  that  should  be  replaced  with  appropriate  values. 
Roman  square  brackets  ([])  indicate  that  thecontents  areoptional. 
Roman  braces  ({})  indicatea  required  element,  usually  in  a  choice. 
Ellipses  (...)  indicate  that  the  previous  element  can  be  repeated. 

Note:  An  argument  beginning  with  a  dash  (-),  a  plus  sign  (+),  or  an  equal  sign  (=)  is  often  defined  as 
a  command  option,  even  if  it  appears  in  a  position  where  a  file  name  could  appear.  Therefore,  it  is 
unwise  to  have  files  names  that  begin  with  -,  +,  or  =. 

DESCRIPTION 

Discusses  the  function  and  behavior  of  each  entry. 

EXTERNAL  INFLUENCES 

Information  under  this  heading  pertains  to  programming  for  various  spoken  languages.  Typical 
entries  indicate  support  for  single-  or  multi byte  characters,  the  effect  of  language-related  environment 
variables  on  system  behavior,  and  other  related  information. 

NETWORKING  FEATURES 

I  nformation  under  this  heading  is  applicableonly  if  you  are  using  the  network  feature  described  there 
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(such  as  NFS). 
RETURN  VALUE 

Describes  the  values  returned  by  function  calls  or  in  the  return  code  by  commands. 
DIAGNOSTICS 

Describes  diagnostic  information  that  may  be  produced.  Self-explanatory  messages  are  not  listed. 
ERRORS 

Lists  function  error  conditions  (set  in  errno)  and  their  corresponding  error  messages. 

EXAMPLES 

Provides  examples  of  typical  usage. 

WARNINGS 

Describes  potential  problems  and  deficiencies. 

DEPENDENCIES 

Describes  variations  in  HP-UX  operation  that  are  related  to  the  use  of  specific  hardware  or  combina- 
tions of  hardware. 

AUTHOR 

I  ndicates  the  origin  of  the  software  documented  by  the  manpage.  Unless  noted  otherwise,  the  source 
of  an  entry  is  System  V. 

FILES 

Lists  file  names  that  are  used  or  affected  by  the  program  or  command. 
SEE  ALSO 

Provides  pointers  to  related  manpages  and  other  documentation. 

STANDARDS  CONFORMANCE 

For  each  command  or  subroutine  entry  point  addressed  by  one  or  more  of  the  following  industry  stan- 
dards, this  section  lists  the  standard  specifications  to  which  that  HP-UX  component  conforms. 

The  various  standards  are: 

AES  OSF  Application  Environment  Specification 

ANSI  C       ANSI  X3.159-1989 

POSIX.l      IEEE  Standard  1003.1-1988 (IEEE  Computer  Society)  (Portable Operating  System  Inter- 
face for  Computer  Environments) 

POSIX.2      IEEE  Standard  1003.2-1990 (IEEE  Computer  Society)  (Portable Operating  System  Inter- 
face for  Computer  Environments) 

POSIX.4     IEEE  Standard  1003.1b- 1993  (IEEE  Computer  Society)  (Portable  Operating  System 
Interface  for  Computer  Environments) 

FIPS  151-1  Federal  Information  Processing  Standard  151-1  (National  Institute  of  Standards  and 
Technology) 

FIPS  151-2  Federal  Information  Processing  Standard  151-2  (National  Institute  of  Standards  and 
Technology) 

SVI D2        System  V  I  nterface  Definition  I  ssue  2 

SVI D3        System  V  I  nterface  Definition  I  ssue  3 

XPG2         X/Open  Portability  Guide  I  ssue  2  (X/Open,  Ltd.) 

XPG3         X/Open  Portability  Guide  I  ssue  3  (X/Open,  Ltd.) 

XPG4         X/Open  Portability  Guide  I  ssue  4  (X/Open,  Ltd.) 

XPG4.2       X/Open  Portability  Guide  I  ssue  4  (X/Open,  Ltd.)  Version  2 

GETTING  STARTED  WITH  HP-UX 

This  is  a  very  brief  overview  of  how  to  use  the  HP-UX  system:  how  to  log  in  and  log  out,  how  to  communi- 
cate through  your  machine,  and  how  to  run  a  program. 

HP-UX  uses  control  characters  to  perform  certain  functions.  Control  characters  are  generally  shown  in 
the  form  "x,  such  as  "D  for  Control-D.  Hold  down  the  Control  (Ctrl)  key  while  you  press  the  character 
key. 
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Logging  In 

To  log  in  you  must  have  a  valid  user  name  and  password,  which  can  be  obtained  from  your  system  adminis- 
trator. 

When  a  connection  has  been  established,  the  system  displays  login:  on  your  terminal.  Type  your  user 
name  and  press  the  Return  key.  Enter  your  password  (it  is  not  echoed  by  the  system)  and  press  Return. 

A  list  of  copyright  notices  and  a  message-of-the-day  may  greet  you  before  the  first  prompt. 

It  is  important  that  you  type  your  login  name  with  lowercase  letters,  if  possible.  If  you  type  uppercase 
letters,  HP-UX  assumes  that  your  terminal  cannot  generate  lowercase  letters,  and  treats  subsequent 
uppercase  input  as  lowercase. 

When  you  log  in  successfully,  the  system  starts  your  login  shell.  The  default  is  the  POSIX  shell, 
/usr/bin/sh.  The  POSIX  shell  (and  its  predecessors,  the  Korn  and  Bourne  shells)  use  $  as  the  default 
prompt.  TheC  shell  uses  %. 

See  login(l)  for  more  on  login,  passwd(l)  to  change  your  password,  chsh(l)  to  change  your  login  shell. 
Loggi  ng  Out 

You  can  log  out  of  the  shells  by  typing  an  exit  command  or  the  eof  (end-of-file)  character  (see  the  Spe- 
cial Interactive  Characters  subsection  below).  The  shell  terminates  and  the  login:  prompt  appears 
again.  (If  you  are  using  the  C,  Korn,  or  POSIX  shells,  respectively,  see  csh(l),  ksh(l),  or  sh-posix(l)  for 
information  about  the  ignoreeof  special  command.) 

How  to  CommunicateThrough  Your  Terminal 

HP-UX  gathers  keyboard  input  characters  and  saves  them  in  a  buffer.  The  accumulated  characters  are  not 
passed  to  the  shell  or  other  program  until  you  type  Return. 

HP-UX  terminal  input/output  is  full-duplex.  It  has  full  read-ahead,  which  means  that  you  can  type  at  any 
time,  even  while  a  program  is  printing  on  your  display  or  terminal.  Of  course,  if  you  type  during  output, 
the  output  display  will  have  the  input  characters  interspersed  in  it.  However,  whatever  you  type  will  be 
saved  and  interpreted  in  the  correct  sequence.  There  is  a  limit  to  the  amount  of  read-ahead,  but  it  is  gen- 
erous and  not  likely  to  be  exceeded  unless  the  system  is  severely  overloaded  or  operating  abnormally. 
When  the  read-ahead  limit  is  exceeded,  the  system  throws  away  all  the  saved  characters. 

stty(l)  tells  you  how  to  describe  the  characteristics  of  your  terminal  to  the  system.  profile(4)  explains  how 
to  accomplish  this  task  automatically  every  time  you  log  in. 

Special  Interactive  Characters 

A  number  of  special  characters  are  used  to  control  the  input  and  output  of  your  terminal.  These  characters 
have  defaults  and  can  be  redefined  with  the  stty  command  (see  stty(l)). 


stty 

Default  At  Login 

Common 

Name 

Character  (ASCII  Name;  Key  Names) 

Redefinition 

eof 

AD  (EOT) 

erase 

# 

AH  (BS;  Backspace) 

kill 

@ 

AU  (NAK),  "X  (CAN) 

intr 

"?  (DEL;  Delete,  Rub,  Rubout) 

AC  (ETX) 

quit 

"A  (FS) 

start 

~Q(DC1;  X-ON) 

stop 

"S  (DC3;  X-OFF) 

The  eof  character  terminates  "file"  input  from  the  terminal,  as  read  by  programs  and  scripts.  By  exten- 
sion, eof  can  also  terminate  the  shell  (seethe  Logging  Out  subsection  above). 

The  kill  character  deletes  all  characters  typed  before  it  on  a  terminal  input  line.  The  erase  character 
erases  the  last  character  typed.  Successive  uses  of  erase  will  erase  characters  back  to,  but  not  beyond, 
the  beginning  of  the  input  line. 

The  intr  character  generates  an  interrupt  signal  that  bypasses  the  input  buffer.  This  signal  generally 
causes  whatever  program  you  are  running  to  terminate.  It  can  be  used  to  stop  a  long  printout  that  you 
don't  want.  However,  programs  can  arrange  either  to  ignore  this  signal  altogether,  or  to  be  notified  when  it 
happens  (instead  of  being  terminated).  For  example,  the  vi  editor  catches  interrupts  and  stops  what  it  is 
doing,  instead  of  terminating,  so  that  an  interrupt  can  be  used  to  halt  an  editing  operation  without  losing 
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the  file  being  edited. 

The  quit  character  generates  a  quit  signal  that  bypasses  the  input  buffer  and  most  program  traps  and 
causes  a  running  program  to  terminate.  It  can  cause  a  core  dump  in  the  current  directory. 

The  stop  character  can  be  used  to  pause  output  to  the  terminal.  It  is  commonly  used  on  video  terminals 
to  suspend  output  to  the  display  while  you  read  what  is  already  being  displayed.  You  can  then  resume  out- 
put by  typing  the  start  character.  When  stop  and  start  are  used  to  suspend  or  resume  output,  they 
bypass  the  keyboard  command-line  buffer  and  are  not  passed  to  the  program.  However,  any  other  charac- 
ters typed  on  the  keyboard  are  saved  and  used  as  input  later  in  the  program. 

The  eof ,  erase,  and  kill  characters  can  be  used  as  normal  text  characters  if  you  escape  them  with  a 
preceding  \,  as  in  \"D.  Therefore,  to  erase  a  \,  you  need  two  erases. 

Theintr,  quit,  start,  and  stop  characters  cannot  be  escaped  on  theinput  line. 

End-of-Line  and  Tab  Characters 

Besides  adapting  to  the  speed  of  the  terminal,  HP-UX  tries  to  be  intelligent  as  to  whether  you  have  a  termi- 
nal with  a  newline  (line-feed)  key,  or  whether  it  must  be  simulated  with  a  return/line-feed  character  pair. 
I  n  the  latter  case,  all  incoming  return  characters  are  changed  to  line-feed  characters  (the  standard  line  del- 
imiter), and  a  return/line-feed  pair  is  echoed  to  the  terminal.  If  you  get  into  the  wrong  mode,  use  the 
stty  command  to  correct  it  (see  stty(l)). 

Tab  characters  are  used  freely  in  HP-UX  source  programs.  If  your  terminal  does  not  have  the  tab  function, 
you  can  arrange  to  have  tab  characters  changed  into  spaces  during  output,  and  echoed  as  spaces  during 
input.  The  stty  command  sets  or  resets  this  mode.  By  default,  the  system  assumes  that  tabs  are  set 
every  eight  character  positions.  The  tabs  command  (see  tabs(l))  can  set  tab  stops  on  your  terminal,  if  the 
terminal  supports  tabs. 

How  to  Run  a  Program 

When  you  have  successfully  logged  into  HP-UX,  the  shell  monitors  input  from  your  terminal.  The  shell 
accepts  typed  lines  from  the  terminal,  splits  them  into  command  names  and  arguments,  then  executes  the 
command.  The  command  can  be  the  name  of  a  shell  built-in,  an  executable  script  of  commands,  or  an  exe- 
cutable program.  There  is  nothing  special  about  system-provided  commands,  except  that  they  are  kept  in 
directories  where  the  shell  can  find  them.  You  can  also  keep  commands  in  your  own  directories  and 
arrange  for  the  shel  I  to  find  them  there. 

The  command  name  is  the  first  word  on  an  input  line  to  the  shell;  the  command  and  its  arguments  are 
separated  from  one  another  by  blanks  (one  or  more  space  and/or  tab  characters). 

When  a  program  terminates,  the  shell  ordinarily  regains  control  and  prompts  you  to  indicate  that  it  is 
ready  for  another  command.  The  shell  has  many  other  capabilities,  which  are  described  in  detail  in  the 
appropriate  manpages:  sh-posix(l)  for  the  POSIX  shell,  ksh(l)  for  the  Korn  shell,  sh-bourne(l)  for  the 
Bourne  shell,  or  csh(l)  for  the  C  shell. 

The  Current  Directory 

HP-UX  has  a  file  system  arranged  in  a  hierarchy  of  directories.  When  the  system  administrator  gave  you  a 
user  name,  he  or  she  also  created  a  directory  for  you  (ordinarily  with  the  same  name  as  your  user  name, 
and  known  as  your  login  or  home  directory).  When  you  log  in,  that  directory  becomes  your  current  or  work- 
ing directory,  and  any  file  name  you  type  is  assumed  to  be  in  that  directory  by  default.  Because  you  are  the 
owner  of  this  directory,  you  have  full  permission  to  read,  write,  alter,  or  destroy  its  contents.  The  permis- 
sions you  have  for  other  directories  and  files  will  have  been  granted  or  denied  to  you  by  their  respective 
owners,  or  by  the  system  administrator.  To  change  the  current  working  directory  usecd(l). 

Path  Names 

To  refer  to  files  not  in  the  current  directory,  you  must  use  a  path  name.  Full  (absolute)  path  names  begin 
with  /,  which  is  the  name  of  the  root  directory  of  the  whole  file  system.  After  the  slash  comes  the  name  of 
each  directory  containing  the  next  subdirectory  (followed  by  a  /),  until  finally  the  file  name  is  reached  (for 
example,  /usr/ae/f  ilex  refers  to  file  f  ilex  in  directory  ae,  while  ae  is  itself  a  subdirectory  of  usr; 
usr  is  a  subdirectory  of  the  root  directory).  See  glossary(9)  for  a  formal  definition  of  path  name. 

If  your  current  directory  contains  subdirectories,  the  path  names  of  files  in  them  begin  with  the  name  of 
the  corresponding  subdirectory  (without  a  prefixed  /).  Generally,  a  path  name  can  be  used  anywhere  a  file 
name  is  required. 

Important  commands  that  modify  the  contents  of  directories  are  cp,  mv,  and  rm  which  respectively  copy, 
move  (that  is,  rename,  relocate,  or  both),  and  remove  files.  To  determine  the  status  of  files  or  the  contents 
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of  directories,  use  the  Is  command.  Usemkdir  to  make  directories,  rmdir  to  destroy  them,  and  mv  to 
rename  them  (seecp(l),  ls(l),  mkdir(l),  mv(l),  rm(l),  and  rmdir(l)). 

Writing  a  Program 

To  enter  the  text  of  a  source  program  into  an  HP-UX  file,  use  a  text  editing  program  such  as  vi,  ex,  or  ed 
(see  vi  (1),  ex(l),  and  ed(l)).  The  three  principal  languages  avail  able  under  HP-UX  areC  (see  ccbundled(l) 
and  cc(l)),  FORTRAN  (seef77(l)),  and  Pascal  (see  pc(l)).  After  the  program  text  has  been  entered  with  the 
editor  and  written  into  a  file  (whose  name  has  the  appropriate  suffix),  you  can  give  the  name  of  that  file  to 
the  appropriate  language  processor  as  an  argument.  Normally,  the  output  of  the  language  processor  will  be 
left  in  a  file  named  a .  out  in  the  current  directory.  Since  the  results  of  a  subsequent  compilation  may  also 
be  placed  in  a. out,  thus  overwriting  the  current  output,  you  may  want  to  usemv  to  give  the  output  a 
unique  name.  If  the  program  is  written  in  assembly  language,  you  will  probably  need  to  link  library  sub- 
routines with  it  (see  I d (1)).  FORTRAN,  C,  and  Pascal  call  the  linker  automatically. 

When  you  have  gone  through  this  entire  process  without  encountering  any  diagnostics,  the  resulting  pro- 
gram can  be  run  by  giving  its  name  to  the  shell  in  response  to  the  prompt. 

Your  programs  can  receive  arguments  from  the  command  linejust  as  system  programs  do  by  using  the  argc 
and  argv  parameters.  See  the  supplied  C  tutorial  for  details. 

Text  Processing 

Almost  all  text  isentered  through  a  text  editor.  Theeditor  preferred  aboveall  others  provided  with  HP-UX 
is  the  vi  editor.  For  batch-processing  text  files,  the  sed  editor  is  very  efficient.  Other  editors  are  used 
much  I  ess  frequently.  Theex  editor  isuseful  for  handling  certain  situations  whileusingvi  but  most  other 
editors  are  rarely  used  except  in  various  scripts. 

The  following  editors  are  the  same  program  masquerading  under  various  names:  vi,  view,  and  vedit 
(see  vi (1))  and  ex  and  edit  (seeex(l)).  For  information  about  the  sed  stream  editor,  see sed(l).  Theed 
line  editor  is  described  in  ed(l). 

The  commands  most  often  used  to  display  text  on  a  terminal  are  cat,  more,  and  pr  (see  cat(l),  more(l), 
and  pr(l)).  The  cat  command  simply  copies  ASCII  text  to  the  terminal,  with  no  processing  at  all.  The 
more  command  displays  text  on  the  terminal  a  screenful  at  a  time,  pausing  for  an  acknowledgement  from 
the  user  before  continuing.  Thepr  command  paginates  text,  supplies  headings,  and  has  a  facility  for  mul- 
ticolumn  output,  pr  is  most  commonly  used  in  conjunction  with  the  lp  command  (see  lp(l))  to  pipe  for- 
matted text  to  a  line  printer. 

Interuser  Communication 

Certain  commands  provide  interuser  communication.  Even  if  you  do  not  plan  to  use  them,  it  could  be 
beneficial  to  learn  about  them,  because  someone  else  may  direct  them  toward  you.  To  communicate  with 
another  user  that  is  currently  logged  in,  you  can  use  write  to  transfer  text  directly  to  that  user's  terminal 
display  (if  permission  to  do  so  has  been  granted  by  the  other  user).  Otherwise,  elm,  mailx,  or  mail  (in 
order  of  ease  of  use)  can  send  a  message  to  another  user's  mailbox.  The  user  is  then  informed  by  HP-UX 
that  mail  has  arrived  (if  currently  logged  in)  or  mail  is  present  (when  the  user  next  logs  in).  Refer  to 
elm(l),  mail  (1),  mailx(l),  and  write(l)  for  explanations  of  how  these  commands  are  used. 
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SEE  ALSO 

cat(l),  cc  bundled(l),  cd(l),  chsh(l),  cp(l),  csh(l),  ed(l),  ex(l),  ksh(l),  ld(l),  login(l),  lp(l),  ls(l),  mail(l), 
mailx(l),  man(l),  mkdir(l),  more(l),  mv(l),  passwd(l),  pr(l),  rm(l),  rmdir(l),  sed(l),  sh(l),  sh-bourne(l), 
sh-posix(l),  stty(l),  tabs(l),  vi(l),  write(l),  a.out(4),  profile(4),  glossary(9). 
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NAME 

intro-  introduction  to  command  utilities  and  application  programs 
DESCRIPTION 

This  section  describes  commands  accessible  by  users,  as  opposed  to  system  calls  in  Section  (2)  or  library 
routines  in  Section  (3),  which  are  accessible  by  user  programs. 

Command  Syntax 

Unless  otherwise  noted,  commands  described  in  this  section  accept  options  and  other  arguments  according 
to  the  fol  I  owi  ng  syntax: 

name[  option  (  s  )]  [  cmdarg  (  s  )] 

where  the  elements  are  defined  as  follows: 

name       Name  of  an  executable  file. 

option      One  or  more  options  can  appear  on  a  command  line.  Each  takes  one  of  the  fol  I  owing  forms: 
-no_arg_letter 

A  singleletter  representing  an  option  without  an  argument. 
-no_arg_letters 

Two  or  more  single-letter  options  combined  into  a  single  command-line  argu- 
ment. 

-a  rgl  etter  oopta  rg 

A  single-letter  option  followed  by  a  required  argument  where: 
argletter 

is  the  singleletter  representing  an  option  that  requires  an  argument, 
optarg 

is  an  argument  (character  string)  satisfyingthe  preceding  arg  letter, 
o    represents  optional  white  space. 

cmd  arg  Path  name  (or  other  command  argument)  not  beginning  with  -,  or  -  by  itself  indicating 
the  standard  input.  If  two  or  more  cmdargs  appear,  they  must  be  separated  by  white 
space. 

Manual  Entry  Formats 

All  manual  entries  follow  an  established  topic  format,  but  not  all  topics  are  included  in  each  entry. 

NAME  Gives  the  name(s)  of  the  entry  and  briefly  states  its  purpose. 

SYNOPSIS  Summarizes  the  use  of  the  entry  or  program  entity  being  described.  A  few  conven- 

tions are  used: 

Computer  font  strings  are  literals,  and  are  to  be  typed  exactly  as  they  appear  in 
the  manual  (except  for  parameters  in  the  SYNOPSIS  section  of  entries  in  Sections  2 
and  3). 

Italic  strings  represent  substitutable  argument  names  and  names  of  manual  entries 
found  elsewhere  in  the  manual. 

Square  brackets  []  around  an  argument  name  indicate  that  the  argument  is  optional. 

Ellipses  (...)  are  used  to  show  that  the  previous  argument  can  be  repeated. 

A  final  convention  is  used  by  the  commands  themselves.  An  argument  beginning  with 
a  dash  (-),  a  plus  sign  (+),  or  an  equal  sign  (=)  is  often  taken  to  be  some  sort  of  option 
argument,  even  if  it  appears  in  a  postion  where  a  file  name  could  appear.  Therefore  it 
is  unwise  to  have  file  names  that  begin  with  -,  +,  or  - 

DESCRIPTION       Discusses  the  function  and  behavior  of  each  entry. 

EXTERNAL  INFLUENCES 

Information  under  this  heading  pertains  to  programming  for  various  spoken 
languages.  Typical  entries  indicate  support  for  single-  and/or  multi-byte  characters, 
the  effect  of  language-related  environment  variables  on  system  behavior,  and  other 
related  information. 
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NETWORKING  FEATURES 

Information  under  this  heading  is  applicable  only  if  you  are  using  the  networking 
feature  described  there  (such  as  NFS). 

RETURN  VALUE     Discusses  various  val  ues  returned  upon  completion  of  program  calls. 

DIAGNOSTICS       Discusses  diagnostics  indications  that  may  be  produced.  Self-explanatory  messages 
are  not  listed. 

ERRORS  Lists  error  conditions  and  their  corresponding  error  message  or  return  value. 

EXAMPLES  Provides  examples  of  typical  usage,  where  appropriate. 

WARNINGS  Points  out  potential  pitfalls. 

DEPENDENCIES     Points  out  variations  in  HP-UX  operation  that  are  related  to  the  user  or  specific 
hardware  or  hardware  combinations. 

AUTHOR  I  ndicatethe  origin  of  the  software  documented  by  the  manual  entry. 

FILES  Lists  file  names  that  are  built  into  the  program  or  command. 

SEE  ALSO  Provides  pointers  to  related  topics. 

BUGS  Discusses  known  bugs  and  deficiencies,  occasionally  suggesting  fixes. 

STANDARDS  CONFORMANCE 

This  section  lists  the  standard  specifications  to  which  the  HP-UX  component  con- 
forms. 

RETURN  VALUE 

Upon  termination,  each  command  returns  two  bytes  of  status,  one  supplied  by  the  system  giving  the  cause 
for  termination,  and  (in  the  case  of  "normal"  termination)  one  supplied  by  the  program  (for  descriptions, 
see  wait(2)  and  exit(2)).  The  system-supplied  byte  is  0  for  normal  termination.  The  byte  provided  by  the 
program  is  customarily  0  for  successful  execution  and  non-zero  to  indicate  errors  or  failure  such  as 
incorrect  parameters  in  the  command  line,  or  bad  or  inaccessible  data.  Values  returned  are  usually  called 
variously  "exit  code",  "exit  status",  "return  code",  or  "return  value",  and  are  described  only  where  special 
conventions  are  involved. 

WARNINGS 

Some  commands  produce  unexpected  results  when  processing  files  containing  null  characters.  These  com- 
mands often  treat  text  input  lines  as  strings,  and  therefore  become  confused  when  they  encounter  a  null 
character  (the  string  terminator)  within  a  line. 

SEE  ALSO 

getopt(l),  exit(2),  wait(2),  getopt(3C),  hier(5),  introduction(9). 
Web  access  to  H  P-UX  documentation  at  http :  //docs  .  hp .  com. 
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NAME 

adb,  adb64-  absolute  debugger 
SYNOPSIS 

adb  [-w]  [-Idir]  [-k]  [-m]  [-Ppid]  objfil  [corfil ] 
adb64  [-w]  [-Idir]  [-k]  [-m]  [-Ppid]  objfil  [corfil] 

DESCRIPTION 

The  adb  command  executes  a  general-purpose  debugging  program  that  is  sensitive  to  the  underlying  archi- 
tecture of  the  processor  and  operating  system  on  which  it  runs.  It  can  be  used  to  examinefiles  and  provide 
a  controlled  environment  for  executing  HP-UX  programs. 

adb  calls  adb 6 4  to  process  64  bit  files. 

objfil  is  normally  an  executable  program  file,  or  an  HP-UX  kernel  (vmunix),  preferably  containing  a  symbol 
table;  if  not,  the  symbolic  features  of  adb  cannot  be  used,  although  the  file  can  still  be  examined.  The 
default  for  objfil  is  a .  out . 

corfil  is  assumed  to  be  a  core  image  file  produced  after  executing  objfil  or  an  HP-UX  crash  file  produced 
from  the  objfil .  The  default  for  corfil  iscore. 

Requests  to  adb  are  read  from  standard  input  and  adb  responds  on  standard  output.  If  the  -w  flag  is 
present,  objfil  is  created  (if  necessary)  and  opened  for  reading  and  writing,  to  be  modified  using  adb.  The 
-I  option  specifies  a  directory  where  files  read  with  $<  or  $<<  (see  below)  are  sought;  the  default  is 
/usr/lib/adb .  adb  ignores  QUIT;  INTERRUPT  causes  return  to  the  next  adb  command. 

The  foil  owing  options  are  also  supported: 

-k  Allows  adb  to  read  objfil  as  an  HP-UX  kernel  file  and  corfil  as  an  HP-UX  crash  dump.  This  also 

allows  virtual -to-physical  address  translation,  useful  for  kernel  debugging.  In  this  case,  corfil 
should  be  an  HP-UX  crash  dump  or  /dev/mem.  Without  -k  or  -m,  adb  treats  objfil  as  an 
application  program  file  and  corfil  as  an  application  core  file. 

When  adb  is  invoked  with  this  option,  it  sets  up  the  context  of  the  currently  running  process 
using  space  registers  four  through  seven.  A  user  specified  address  is  dereferenced  by  combining 
it  with  the  appropriate  space  register,  depending  on  the  quadrant  in  which  the  32-bit  address 
lies. 

When  the  current  radix  is  not  (decimal)  ten,  the  -k  option  allows  adb  to  support  the  notion  of 
long  pointers  or  addresses  in  the  form  space. offset.  Once  a  space  is  specified,  all  subsequent 
addresses  are  dereferenced  using  that  space  until  the  user  enters  another  long  address.  If  a 
space  equal  to  (hexadecimal)  Oxffffffff  is  used,  adb  reverts  to  the  previous  context  and  uses  space 
registers  four  through  seven  to  dereference  32-bit  addresses. 

-m  Must  be  specified  instead  of  -k  when  a  core  dump  is  written  to  multiplexes. 

When  -m  is  used,  corfil  must  be  specified  as  the  path  name  of  the  directory  that  contains  system 
core  dump  files.  A  command  line  using -m  might  look  similar  to  the  foil  owing: 

adb  -m  /var/adm/ crash/core . 1 /vmunix  /var/adm/crash/core . 1 

Notice  that  when  -m  is  specified  on  the  command  line,  -k  is  not  necessary. 

-Ppid      Causes  adb  to  adopt  process  pid  as  a  "traced"  process  (see  ptrace(2)).  This  option  is  helpful  for 
debugging  processes  that  were  not  originally  run  under  the  control  of  adb. 

Requests  to  adb  follow  the  form: 

[address]  [,  count]  [command]  [;  ] 

If  address  is  present,  dot  is  set  to  address.  I  nitially  dot  is  set  to  0.  For  most  commands,  count  specifies  the 
number  of  times  the  command  is  to  be  executed.  The  default  count  is  1.  address  and  count  are  expres- 
sions. 

The  interpretation  of  an  address  depends  on  the  context  in  which  it  is  used.  If  a  subprocess  is  being 
debugged,  addresses  are  interpreted  in  the  address  space  of  the  subprocess.  (For  further  details  of  address 
mapping  see  Addresses  below.) 
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Expressions 

Expressions  are  interpreted  as  follows: 

The  value  of  dot. 
+  The  value  of  dot  increased  by  the  current  increment. 

A  The  val  ue  of  dot  decreased  by  the  current  decrement. 

The  last  address  typed. 

integer  A  number.  The  prefix  0  (zero)  forces  interpretation  in  octal  radix;  the  prefixes  Od  and 
OD  force  interpretation  in  decimal  radix;  the  prefixes  Ox  and  OX  force  interpretation  in 
hexadecimal  radix.  Thus  020  =  0dl6  =  0x10  =  sixteen.  If  no  prefix  appears,  the 
default  radix  is  used;  see  the  $d  command.  The  radix  is  initialized  to  the  base  used  in 
the  assembly  language  for  the  processor  involved.  Note  that  a  hexadecimal  number 
whose  most  significant  digit  would  otherwise  bean  alphabetic  character  must  have  a  Ox 
(or  OX)  prefix. 

integer .  fraction 

A  32-bit  floating-point  number. 

'  cccc'  The  ASCII  value  of  up  to  4  characters.  A  backslash  (\)  can  be  used  to  escape  a  single 
quote  (' ). 

<  name  name  can  have  the  value  of  either  a  variable  or  a  register,  adb  maintains  a  number  of 
variables  named  by  single  letters  or  digits;  see  Variables  below.  If  name  is  a  register,  the 
value  of  the  register  is  obtained  from  the  COREPROC  segment  in  corfil  (before  the  sub- 
process  is  initiated)  or  from  the  user  area  of  the  subprocess.  Register  names  are  imple- 
mentation dependent;  seethe  $r  command. 

symbol  A  symbol  is  a  sequence  of  uppercase  or  lowercase  letters,  underscores,  or  digits,  not  start- 
ing with  a  digit.  A  backslash  (\)  can  be  used  to  escape  other  characters.  The  value  of  the 
symbol  is  taken  from  the  symbol  table  in  objfil .  An  initial  underscore  (_)  is  prefixed  to 
symbol ,  if  needed. 

_  symbol  If  the  compiler  prefixes  _  to  an  external  symbol,  it  may  be  necessary  to  cite  this  name  to 
distinguish  it  from  a  symbol  generated  in  assembly  language. 

(exp)  The  value  of  the  expression  exp. 

The  foil  owing  are  monadic  operators: 

*exp  The  contents  of  the  location  addressed  by  exp  in  corfil. 

@exp         Thecontents  of  the  location  addressed  by  exp  in  objfil. 

-exp  I  nteger  negation. 

~exp  Bitwise  complement. 

The  foil  owing  dyadic  operators  are  left  associative  and  are  less  binding  than  monadic  operators: 


el+e2 

1  nteger  addition. 

el-e2 

1  nteger  subtraction. 

el*e2 

Integer  multiplication. 

el%e2 

1  nteger  division. 

el&e2 

Bitwise  conjunction. 

el|e2 

Bitwise  disjunction. 

el#e2 

el  rounded  up  to  the  next  multipleof  e2. 

Commands 

Most  commands  consist  of  an  action  character  followed  by  a  modifier  or  list  of  modifiers.  The  following 
action  characters  can  take  format  specifiers.  (The  action  characters  ?  and  /  can  be  followed  by  *;  see 
Addresses  for  further  details.) 

?f  Locations  starting  at  address  in  objfil  are  printed  according  to  the  format  f.  dot  is  incre- 

mented by  the  sum  of  the  i ncrements  for  each  format  letter.  If  a  subprocess  has  been  ini- 
tiated, address  references  a  location  in  the  address  space  of  the  subprocess  instead  of 
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objfil . 

/f  Locations  starting  at  address  in  corfil  are  printed  according  to  the  format  f  and  dot  is 

increased  like  ?,  If  a  subprocess  has  been  initiated,  address  refers  to  a  location  in  the 
address  space  of  the  subprocess  i  nstead  of  corfil . 

=f  The  value  of  address  is  printed  in  the  styles  indicated  by  the  format  f.  (For  i  format  ? 

is  printed  for  the  parts  of  the  instruction  that  refer  to  subsequent  words.) 

A  format  consists  of  one  or  more  characters  that  specify  a  style  of  printing.  Each  format  character  can  be 
preceded  by  an  integer  that  indicates  how  many  times  the  format  is  repeated.  While  stepping  through  a 
format,  dot  is  increased  by  the  amount  given  for  each  format  character.  If  no  format  is  given  then  the  last 
format  is  used. 

Thefollowing  format  characters  are  available: 


a 

0 

Print  the  value  of  dot  in  symbolicform. 

b 

1 

Print  the  addressed  byte  in  hexadecimal. 

B 

1 

Print  the  addressed  byte  in  octal. 

c 

1 

J. 

Prinl"  thp  arlrlroccoH  r'harprtpr  /thp  ci nn  hit"  ic  innnrprH 
rllllL  LI  Ic  dUUI  cbbcU  LI  Idl  aLLCl    \LllcbiyilUILIbiyilUI  cU/. 

1 

Pri  nt  thp  arlnYpccprl  rharart'pr"  i  i  ci  nn  1~hp  fnl  1  nwi  nn  pcranp  rnn\/pn  1~i nn    F  i  ret"  1~hp  ci  nn  hit  i c 

r  1  MIL  LI  IC  UUUI  CJJCU  LI  lul  ULLG    Ual  1  1  y  LI  IC  1  \J\  1  KJVV  iiiy  ~z>v_a  IJ  ~  LUI  IVG  1  LI  \J\  1 .     Ill  JL,  LI  IC  Jl  yl  1  U\  L  1  J 

discarded,  then  character  values  000  to  040  are  printed  as  @  followed  by  the 
corresponding  character  in  the  range  0100  to  0140.  The  character  @is  printed  as@@ 

d 

2 

Print  2  bytes  in  decimal. 

D 

4 

Print  4  bytes  in  decimal. 

f 

4 

Print  the  32  bit  value  as  a  floating  point  number. 

F 

8 

Print  double  floating  point. 

p 

Print  pc  m^rhinp  inctri  irtinnc    Thp  \/^Iiip  nf  n  ic  thp  niimhpr  nf  h\/tpc  nrrimiprl  h\/  thp 
r  i  1 1 1  l  ab  1 1  id*wi  1 1 1 1  c  ii  ibLi  ull  i  uiio.     i  i  ic  veil  uc  ui  ii  lb  li  ic  i  iui  i  iuci    ui   uy  lcj  ullu  |ji  cu  uy  li  ic 

instruction. 

n 

0 

Print  a  new-line  character. 

o 

2 

Print  2  bytes  in  octal.  All  octal  numbers  output  by  adb  are  preceded  by  0. 

0 

4 

Print  4  bytes  in  octal. 

P 

n 

Print  the  addressed  value  in  symbolic  form.  The  value  of  n  is  a  machine-dependent  con- 
stant. 

q 

2 

Print  2  bytes  in  signed  octal. 

Q 

4 

Print  4  bytes  in  signed  octal. 

r 

0 

Print  a  space. 

s 

n 

Print  the  addressed  characters  until  a  zero  character  is  reached. 

S 

n 

Print  a  string  using  the  ©escape  convention.  The  value  n  is  the  length  of  the  string 
including  its  zero  terminator. 

t 

0 

When  preceded  by  an  integer,  moves  to  the  next  appropriate  tab  stop.  For  example,  8t 
moves  to  the  next  8-spacetab  stop. 

u 

2 

Print  2  bytes  as  an  unsigned  decimal  number. 

U 

4 

Print  4  bytes  as  an  unsigned  decimal  number. 

X 

2 

Print  2  bytes  in  hexadecimal. 

X 

4 

Print  4  bytes  in  hexadecimal. 

Y 

4 

Print  4  bytes  in  date  format  (see  ctime(3Q). 

ii 

."  0 

Print  the  enclosed  string. 

A 

dot  is  decreased  by  the  current  increment.  Nothing  is  printed. 

+ 

dot  is  increased  by  1.  Nothing  is  printed. 
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dot  is  decreased  by  1.  Nothing  is  printed. 

new-line 

Repeat  the  previous  command  with  a  count  of  1.  The  value  of  dot  continues  from  the  end  of  the 
previous  format,  unlike  a  [?/]  command  with  no  address,  which  repeats  the  previous  address 
value.  New-linecan  also  be  used  to  repeat  a  :sor  :  c  command;  however,  any  arguments  to  the 
previous  command  are  lost. 

[?/]l  value  mask 

Words  starting  at  dot  are  masked  with  mask  and  compared  with  value  until  a  match  is  found.  If 
L  is  used,  adb  looks  to  match  4  bytes  at  a  time  instead  of  2.  If  no  match  is  found,  dot  is  left 
unchanged;  otherwise  dot  is  set  to  the  matched  location.  If  mask  is  omitted  -1  is  used. 

[?/]w  value... 

Write  the  2-byte  value  into  the  addressed  location.  If  the  command  is  W,  write  4  bytes.  Odd 
addresses  are  not  allowed  when  writing  to  the  subprocess  address  space. 

=m  Toggle  the  address  mapping  of  corfil  between  the  initial  map  set  up  for  a  valid  core  file  and  the 
default  mapping  pair  which  the  user  can  modify  with  /m.  If  the  corfil  was  invalid,  only  the 
default  mapping  is  available. 

[?/]mblelfl[?/] 

Record  new  values  for  (bl,  el,  fl).  If  fewer  than  three  expressions  are  given,  the  remaining  map 
parameters  are  left  unchanged.  If  the  ?  or  /  is  foil  owed  by  *,  the  second  segment  (b2,  e2,  f2)  of 
the  mapping  is  changed.  If  the  list  is  terminated  by  ?  or  /,  the  file  (objfil  or  corfil ,  respectively) 
is  used  for  subsequent  requests.  (For  example,  /m?  causes  /  to  refer  to  objfil .)  A  /m  command 
switches  the  corfil  mapping  to  the  default  mapping  pair.  For  a  valid  core  file,  the  =m  command 
can  be  used  to  switch  back  to  the  initial  mapping. 

>name 

Assign  dot  to  the  variable  or  register  named. 

!      Call  a  shell  to  read  the  remainder  of  the  line  foil  owing  ! . 

Thefollowing  $  commands  take  the  form  $modifier: 

$<f  Read  commands  from  the  file  f.  If  this  command  isexecuted  in  a  file,  further  commands 

in  the  file  are  not  seen.  If  a  count  is  given,  and  is  zero,  the  command  is  ignored.  The 
value  of  the  count  is  placed  in  variable 9  before  the  first  command  in  f  is  executed. 

$<<f  Similar  to  $<  except  it  can  be  used  in  a  file  of  commands  without  causing  the  file  to  be 
closed.  Variable  9  is  saved  when  the  command  executes  and  is  restored  when  it  com- 
pletes. Only  five  $<<  files  can  be  open  at  once. 

$>f  Send  output  tothefilef,  which  is  created  if  it  does  not  already  exist. 

$new-line    Print  the  process  id  and  register  values. 

$b  Print  all  breakpoints  and  their  associated  counts  and  commands. 

$c  C  stack  backtrace.  If  address  is  given,  it  is  taken  as  the  address  of  the  current  frame 

(instead  of  the  normal  stack  frame  pointer).  If  count  is  given,  only  the  first  count  frames 
are  printed. 

$d  Set  the  default  radix  to  address  and  report  the  new  value.  Note  that  address  is  inter- 

preted in  the  (old)  current  radix.  Thus  10$d  never  changes  the  default  radix.  To  make 
decimal  the  default  radix,  useOdlO$d. 

$e  The  names  and  values  of  external  variables  are  printed. 

$f  Print  the  floating-point  registers. 

$m  Print  the  address  map.  This  includes  both  the  initial  and  default  maps  for  a  valid  corfil 

with  an  indication  of  which  is  currently  active. 

$N  [nodenumber] 

Print  the  number  of  nodes  on  V-class  multinode  machines  and  the  current  node  number. 
To  switch  to  another  node,  enter  $N  nodenumber. 

$o  The  default  for  all  integers  input  is  octal. 

$q  Exit  from  adb. 
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$r  Print  the  general  registers  and  the  instruction  addressed  by  the  process  counter,  dot  is 

set  to  the  process  counter  contents. 

$s  Set  the  limit  for  symbol  matches  to  address.  The  default  is  system  dependent. 

$v  Print  all  non-zero  variables  in  thecurrent  radix. 

$w  Set  the  page  width  for  output  to  address  (default  80). 

$x  The  default  for  all  integers  input  is  hexadecimal. 

$z  Print  a  list  of  signals  and  how  they  are  handled.  See  :  z  for  information  on  changing  sig- 
nal handling. 

Theavailable  :  commands  manage  subprocesses,  and  take  the  form  :modifier: 

:bc  Set  breakpoint  at  address.  The  breakpoint  is  executed  count-1  times  before  causing  a 

stop.  Each  time  the  breakpoint  is  encountered,  the  command  c  is  executed.  If  this  com- 
mand sets  dot  to  zero,  the  breakpoi  nt  causes  a  stop. 

:  cs  Continue  the  subprocess  with  signal  s  (see  signal  (5)).  If  address  is  given,  the  subprocess 

continues  at  this  address.  If  no  signal  is  specified,  the  signal  that  caused  the  subprocess 
to  stop  is  sent.  Breakpoint  skipping  is  the  same  as  for  :r. 

:d  Delete  breakpoint  at  address.  :d*  deletes  all  breakpoints. 

:e  Set  up  a  subprocess  as  in  :r;  no  instructions  are  executed. 

:k  Terminate  the  current  subprocess,  if  any. 

:  r  Run  objfil  as  a  subprocess.  If  address  is  given  explicitly,  the  program  is  entered  at  this 


point;  otherwise  the  program  is  entered  at  its  standard  entry  point.  The  value  count 
specifies  how  many  breakpoints  are  ignored  before  stopping.  Arguments  to  the  subpro- 
cess may  be  supplied  on  the  same  line  as  the  command.  An  argument  starting  with  <  or 
>  causes  the  standard  input  or  output  to  be  established  for  the  command.  All  signals  are 
turned  on  when  entering  the  subprocess. 

:  ss  As  for  c  except  that  the  subprocess  is  single  stepped  count  times.  If  there  is  no  current 

subprocess,  objfil  is  run  as  a  subprocess  as  for  :  r.  I  n  this  case  no  signal  can  be  sent;  the 
remainder  of  the  line  is  treated  as  arguments  to  the  subprocess. 

:  Ss  Same  as  :  c  except  that  a  temporary  breakpoint  is  set  at  the  next  instruction.  Useful  for 

stepping  across  subroutines. 

:x  a  [b]...  Execute subroutinea  with  parameters  [b]... 

:  zd  Change  signal  handlingfor  a  specified  signal.  Disposition  d  can  be  specified  as: 

+s    Stop  process  when  signal  is  received. 

-s    Do  not  stop  process  when  signal  is  received. 

+r    Report  when  signal  is  received. 

-r    Do  not  report  when  signal  is  received. 

+d   Deliver  signal  to  the  target  process. 

-d   Do  not  deliver  signal  to  the  target  process. 

For  example,  0x10 :  z+d  enables  delivering  of  signal  number  0x10  to  the  target  pro- 
cess. Use$z  to  display  existing  settings. 

Variables 

adb  provides  named  and  numbered  variables.  Named  variables  are  set  initially  by  adb  but  are  not  used 
subsequently.  Numbered  variablesare  reserved  for  communication  as  follows: 


0  The  last  value  printed. 

1  The  last  offset  part  of  an  instruction  source. 

2  Theprevious  valueof  variablel. 

9  The  count  on  the  last  $<  command. 
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On  entry,  the  foil  owing  named  variables  are  set  from  the  coreheaders  in  the  corfil .  If  corfil  does  not  appear 
to  be  a  core  file,  these  values  are  set  from  objfil . 


b  The  base  address  of  the  data  segment, 

d  The  data  segment  size, 

s  The  stack  segment  size, 

t  The  text  segment  size. 
The  foil  owing  variables  are  set  from  objfil . 

e  The  entry  point. 

m  The  "magic"  number  as  defined  in  <magic.h>. 
Addresses 


The  file  address  associated  with  a  written  address  is  determined  by  a  mapping  described  below;  see  $m. 
Both  the  objfil  mapping  and  the  default  corfil  mapping  are  represented  by  two  triples  (bl,  el,  fl)  and  (b2, 
e2,  f2).  The  initial  mapping  for  a  valid  corfil  contains  a  triplefor  each  segment  (coreheader). 

The  file  address  corresponding  to  a  written  address  is  calculated  as  follows: 

If 

bl  <=  address  <  el,  then  file  address  =  address  +  fl  -  bl. 
Otherwise,  if 

b2  <=  address  <  e2,  then  file  address  =  address  +  f2  -  b2. 

Otherwise,  the  requested  address  is  not  valid.  For  a  valid  corfil,  this  pattern  repeats  as  many  times  as 
there  are  segments  (coreheaders)  in  the  corfil,  rather  than  twice.  If  ?  or  /  is  followed  by  *,  only  the 
second  triple  is  used,  or  (when  using  the  initial  mapping  of  a  valid  corfil)  only  segments  with  a 
CORE_STACK  coreheader. 

The  initial  setting  of  both  mappings  is  suitablefor  normal  a .  out  and  core  files.  If  either  file  is  not  of  the 
kind  expected,  adb  sets  bl  to  0,  el  to  the  maximum  file  size,  and  fl  to  0;  in  this  way  the  entire  file  can  be 
examined  with  no  address  translation. 

adb  keeps  all  appropriate  values  as  signed  32-bit  integers  so  that  it  can  be  used  on  large  files. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

adb  comments  about  inaccessiblefiles,  syntax  errors,  abnormal  termination  of  commands,  etc.  It  echoes 
adb  when  there  is  no  current  command  or  format.  Exit  status  is  0,  unless  the  last  command  failed  or 
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returned  non-zero  status. 

DEPENDENCIES 

•  Setting  breakpoints  in  shared  libraries  is  not  supported. 

adb  does  not  read  the  linker  symbol  table  for  shared  libraries,  and  cannot  access  locations  in  shared 
libraries  by  name.  In  a  stack  backtrace  ($c),  adb  does  not  know  the  names  of  shared  library  pro- 
cedures. 

If  the  core  file  was  created  when  the  program  was  in  a  shared  library  function,  the  $c  command  does 
not  work.  When  a  stack  backtrace  for  the  core  file  encounters  a  shared  library  procedure  on  the  stack  it 
aborts  at  that  point. 

•  A  leading  zero  by  itself  is  not  recognized  as  a  radix  indicator.  Use  the  prefixes  Oo  or  OO  (zero-oh)  to 
force  interpretation  in  octal  radix.  The  prefixes  Ot  and  OT  are  also  accepted  to  force  interpretation  in 
decimal  radix.  Thus  0o20  =  0tl6  =  sixteen.  A  hexadecimal  number  whose  most  significant  digit 
would  otherwise  bean  alphabetic  character  may  begin  with  a  leading  zero  instead  of  Ox  (or  OX),  if  the 
default  radix  is  hexadecimal. 

•  The  $f  command  prints  floating  point  registers  as  32-bit  single  precision  and  $F  prints  these  registers 
as  64-bit  doubles. 

•  $R  prints  all  registers  avail  able  to  adb  users. 

•  The  :  x  and  :  S  commands  are  not  currently  supported. 

•  adb  can  be  used  to  inspect  relocatable  object  files;  it  reads  the  symbol  table  and  sets  up  the  appropriate 
mappings  for  text  and  data.  Note  that  relocatable  object  files  do  not  necessarily  contain  an  exact  image 
of  the  initialized  data;  however,  if  this  is  the  case,  the  data  mapping  is  not  set. 

AUTHOR 

adb  was  developed  by  AT&T  and  HP. 


a .  out 
core 

/ dev/ mem 
/dev/kmem 
/ dev/ swap 


FILES 


SEE  ALSO 

ptrace(2),  crt0(3),  ctime(3C),  end(3C),  a.out(4),  core(4),  signal(5). 
ADB  Tutorial 
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NAME 

adjust  -  simple  text  formatter 
SYNOPSIS 

adjust  [-b]  [-c|-j|-r]  [-m  column]  [-t  tabsize]  [files  ...] 
DESCRIPTION 

The  adjust  command  is  a  simple  text  formatter  for  filling,  centering,  left  and  right  justifying,  or  only 
right  justifying  text  paragraphs,  and  is  designed  for  interactive  use.  It  reads  the  concatenation  of  input 
files  (or  standard  input  if  none  are  given)  and  produces  on  standard  output  a  formatted  version  of  its  input, 
with  each  paragraph  formatted  separately.  If  -  is  given  as  an  input  filename,  adjust  reads  standard 
input  at  that  point  (use  —  as  an  argument  to  separate  -  from  options.) 

adjust  reads  text  from  input  lines  as  a  series  of  words  separated  by  space  characters,  tabs,  or  newlines. 
Text  lines  are  grouped  into  paragraphs  separated  by  blank  lines.  By  default,  text  is  copied  directly  to  the 
output,  subject  only  to  simplefilling  (see  below)  with  a  right  margin  of  72,  and  leading  spaces  are  converted 
to  tabs  where  possible. 

Options 

Theadjust  command  recognizes  the  following  command-line  options: 

-b  Do  not  convert  leading  space  characters  to  tabs  on  output;  (output  contains  no  tabs,  even  if 

there  were  tabs  in  input). 

-c  Center  text  on  each  line.  Lines  are  pre-  and  post-processed,  but  no  filling  is  performed. 

-  j  J  ustify  text.  After  filling,  insert  spaces  in  each  line  as  needed  to  right  justify  it  (except  in 

thelast  line  of  each  paragraph)  while  keeping  thejustified  left  margin. 

-r  After  filling  text,  adjust  the  indentation  of  each  line  for  a  smooth  right  margin  (ragged  left 

margin). 

-mcolumn 

Set  the  right  fill  margin  to  the  given  column  number,  instead  of  72.  Text  is  filled,  and 
optionally  right  justified,  so  that  no  output  line  extends  beyond  this  column  (if  possible).  If 
-mO  is  given,  the  current  right  margin  of  the  first  line  of  each  paragraph  is  used  for  that 
and  all  subsequent  lines  in  the  paragraph. 

By  default,  text  is  centered  on  column  40.  With  -c,  the  -m  option  sets  the  middle  column 
of  the  centering  "window",  but  -mO  auto-sets  the  right  side  as  before  (which  then  deter- 
mines the  center  of  the  "window"). 

-ttabsize  Set  the  tab  size  to  other  than  the  default  (eight  columns). 

Only  one  of  the  -c,  -  j,  and  -r  options  is  allowed  in  a  singlecommand  line. 

Details 

Before  doing  anything  else  to  a  line  of  input  text,  adjust  first  handles  backspaces,  rubbing  out  preceding 
characters  in  the  usual  way.  Next,  it  ignores  all  non-printable  characters  except  tab.  It  then  expands  all 
tabs  to  spaces. 

For  simpletext  filling,  the  first  word  of  the  first  line  of  each  paragraph  is  indented  the  same  amount  as  in 
the  input  line.  Each  word  is  then  carried  to  the  output  followed  by  one  space.  "Words"  ending  in 
terminal_character[quote][closing_character]  are  followed  by  two  spaces,  where  terminalcharacter  is  any 
of  .,:,?,  or  ! ;  quote  is  a  single  closing  quote  ( '  )  character  or  double-quote  character  (  "  ),  and  close  is 
any  of ) ,  ] ,  or  } .  H  ere  are  some  examples: 

end.  of?  sentence.'  sorts!"  of.)  words?"] 

(adjust  does  not  place  two  spaces  after  a  pair  of  single  closing  quotes  (")  following  a 
terminalcharacter). 

adjust  starts  a  new  output  line  whenever  adding  a  word  (other  than  the  first  one)  to  the  current  line 
would  exceed  the  right  margin. 

adjust  understands  indented  first  lines  of  paragraphs  (such  as  this  one)  when  filling.  The 
second  and  subsequent  lines  of  each  paragraph  are  indented  the  same  amount  as  the  second  line  of  the 
input  paragraph  if  thereisa  second  line,  else  the  same  as  the  first  line. 
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*  adjust  also  has  a  rudimentary  understanding  of  tagged  paragraphs  (such  as  this  one)  when 

filling.  If  the  second  line  of  a  paragraph  is  indented  more  than  the  first,  and  the  first  line  has  a 
word  beginning  at  the  same  indentation  as  the  second  line,  the  input  column  position  of  the  tag 
word  or  words  (prior  to  the  one  matching  the  second  line  indentation)  is  preserved. 

Tag  words  are  passed  through  without  change  of  column  position,  even  if  they  extend  beyond  the  right  mar- 
gin. The  rest  of  the  line  is  filled  or  right  justified  from  the  position  of  the  first  non-tag  word. 

When  -j  is  given,  adjust  uses  an  intelligent  algorithm  to  insert  spaces  in  output  lines  where  they  are 
most  needed,  until  the  lines  extend  to  the  right  margin.  First,  all  one  space  word  separators  are  examined. 
One  space  is  added  to  each  separator,  starting  with  the  one  having  the  most  letters  between  it  and  the 
preceding  and  following  separators,  until  the  modified  line  reaches  the  right  margin.  If  all  one  space 
separators  are  increased  to  two  spaces  and  more  spaces  must  be  inserted,  the  algorithm  is  repeated  with 
two  space  separators,  and  so  on. 

Output  line  indentation  is  held  to  one  less  than  the  right  margin.  If  a  single  word  is  larger  than  the  line 
size  (right  margin  minus  indentation),  that  word  appears  on  a  line  by  itself,  properly  indented,  and  extends 
beyond  the  right  margin.  However,  if  -r  is  used,  such  words  are  still  right  justified,  if  possible. 

If  the  current  locale  defines  class  names  ekinsoku  and  bkinsoku  (see  iswctype(3C)),  adjust  formats 
the  text  in  accordance  with  the  ekinsoku/bkinsoku  character  classification  and  margin  settings  (see  - 
r,  -  j,  and  -m  options). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  adjust  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogs  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

adjust  complains  to  standard  error  and  later  returns  a  nonzero  value  if  any  input  file  cannot  be  opened 
(it  skips  the  file).  It  does  the  same  (but  quits  immediately)  if  the  argument  to  -m  or  -t  is  out  of  range,  or  if 
the  program  is  improperly  invoked. 

Input  lines  longer  than  BUFSIZ  are  silently  split  (before  tab  expansion)  or  truncated  (afterwards).  Lines 
that  are  too  wide  to  center  begin  in  column  1  (no  leading  spaces). 

EXAMPLES 

This  command  is  useful  for  filtering  text  while  in  vi  (1).  For  example, 
! } adjust 

reformats  the  rest  of  the  current  paragraph  (from  the  current  line  down),  evening  the  lines. 

Thevi  command: 

:map  'X  { ! }adjust  -j"V"M 

(where  "  denotes  control  characters)  sets  up  a  useful  "finger  macro".  Typing  "X  (Ctrl-X)  reformats  the 
entire  current  paragraph. 

adjust  -ml  is  a  simple  way  to  break  text  into  separate  words  without  white  space,  except  for  tagged- 
paragraph  tags. 
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WARNINGS 

This  program  is  designed  to  be  simple  and  fast.  It  does  not  recognize  backslash  to  escape  white  space  or 
other  characters.  It  does  not  recognize  tagged  paragraphs  where  the  tag  is  on  a  line  by  itself.  It  knows 
that  lines  end  in  newlineor  null,  and  how  to  deal  with  tabs  and  backspaces,  but  it  does  not  do  anything  spe- 
cial with  other  characters  such  as  form  feed  (they  are  simply  ignored).  For  complex  operations,  standard 
text  processors  are  likely  to  be  more  appropriate. 

This  program  could  be  i mpl emented  instead  as  a  set  of  independent  programs,  fill,  center,  and  justify  (with 
the  -r  option).  However,  this  would  be  much  less  efficient  in  actual  use,  especially  given  the  program's 
special  knowledge  of  tagged  paragraphsand  last  lines  of  paragraphs. 


AUTHOR 

adjust  was  developed  by  HP. 


SEE  ALSO 

nroff(l). 


Section  1-12 


-3- 


HP-UX  Release  Hi:  December  2000 


admin  (1) 


admin  (1) 


NAME 

admin  -  create  and  administer  SCCS  files 
SYNOPSIS 

admin  -i[name]  [-n]  [-b]  [-a  login]  ...  [-d  flag[flag-val]]  ...  [-f  flag[flag-val]]  ... 
[-m  mrlist]  ...  [-r  rel]  [-t[name]]  [-y[comment]]  file  ... 

admin  -n  [-a  login]  ...  [-d  flag[flag-val]]  ...  [-f  flag[flag-val]]  ...  [-m  mrlist]  ... 
[-t[name]]  [-y[comment]]  file  ... 

admin  [-a  login]  ...  [-e  login]  ...  [-d  flag[flag-val]]  ...  [-m  mrlist]  ... 
[-r  rel]  [-t[name]]  file  ... 

admin  -h  file  ... 

admin  -z  file  ... 

DESCRIPTION 

The  admin  command  is  used  to  create  new  SCCS  files  and  change  the  parameters  of  existing  ones.  Argu- 
ments to  admin,  which  may  appear  in  any  order,  (unless  —  is  specified  as  an  argument,  in  which  case  all 
arguments  after  —  are  treated  as  files  )  consist  of  option  arguments,  beginning  with  -,  and  named  files 
(note  that  SCCS  file  names  must  begin  with  the  characters  s . ).  If  a  named  filedoes  not  exist,  it  is  created 
and  its  parameters  are  initialized  according  to  the  specified  option  arguments.  Parameters  not  initialized 
by  an  option  argument  are  assigned  a  default  value.  If  a  named  filedoes  exist,  parameters  corresponding 
to  specified  option  arguments  are  changed,  and  other  parameters  are  left  unaltered. 

If  directory  is  named  instead  of  file,  admin  acts  on  each  file  in  directory,  except  that  non-SCCS  files  (the 
last  component  of  the  path  name  does  not  begin  with  s  . )  and  unreadable  files  are  silently  ignored.  If  a 
name  of  -  is  given,  the  standard  input  is  read,  and  each  line  of  the  standard  input  is  assumed  to  be  the 
name  of  an  SCCS  file  to  be  processed.  Again,  non-SCCS  files  and  unreadable  files  are  silently  ignored. 

The  admin  option  arguments  apply  independently  to  all  named  files,  whether  one  file  or  many.  I  n  the  fol- 
lowing discussion,  each  option  is  explained  as  if  only  one  file  is  specified,  although  they  affect  singleor  mul- 
tiplexes identically. 

Options 

Theadmin  command  supports  the  foil  owing  options  and  command-line  arguments: 
-n  This  option  indicates  that  a  new  SCCS  file  is  to  be  created. 

-i[name]  The  name  of  a  file  from  which  the  contents  for  a  new  SCCS  file  is  to  betaken,  (if  name 
is  a  binary  file,  then  you  must  specify  the  -b  option)  The  contents  constitutes  the  first 
delta  of  the  file  (see  the  -r  option  for  the  delta  numbering  scheme).  If  the  -i  option 
is  used  but  the  file  name  is  omitted,  the  text  is  obtained  by  reading  the  standard  input 
until  an  end-of-file  is  encountered.  If  this  option  is  omitted,  the  SCCS  file  is  created 
with  an  empty  initial  delta.  Only  one  SCCS  file  can  be  created  by  an  admin  com- 
mand on  which  the  -i  option  is  supplied.  Using  a  single  admin  to  create  two  or 
more  SCCS  files  requires  that  they  be  created  empty  (no  -i  option).  Note  that  the  - 
i  option  impliesthe-n  option. 

-b  Encode  the  contents  of  name,  specified  to  the  -i  option.  This  keyletter  must  be  used 

if  name  is  a  binary  file;  otherwise,  a  binary  file  will  not  be  handled  properly  by  SCCS 
commands. 

-r  rel  The  release  (rel )  into  which  the  initial  delta  is  inserted.  This  option  can  be  used  only 

if  the  -i  option  is  also  used.  If  the  -r  option  is  not  used,  the  initial  delta  is  inserted 
into  release  1.  The  level  of  the  initial  delta  is  always  1  (by  default  initial  deltas  are 
named  1.1). 

-t[name]  The  name  of  a  file  from  which  descriptive  text  for  the  SCCS  file  is  to  be  taken.  If  the 
-t  option  is  used  and  admin  is  creating  a  new  SCCS  file  (the  -n  and/or  -i  options 
are  also  used),  the  descriptive  text  file  name  must  also  be  supplied.  In  the  case  of 
existing  SCCS  files: 

•  A  -t  option  without  a  file  name  causes  removal  of  descriptive  text  (if  any) 
currently  in  the  SCCS  file. 

•  A  -t  option  with  a  file  name  causes  text  (if  any)  in  the  named  file  to  replace 
the  descriptive  text  (if  any)  currently  in  the  SCCS  file. 
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-f  flag  This  option  specifies  a  flag,  and  possibly  a  value  for  the  flag,  to  be  placed  in  the  SCCS 

file.  Several  -f  options  can  besupplied  on  a  singleadmin  command  line.  Theallow- 
able flags  and  their  values  are: 

b  Allows  use  of  the  -b  option  on  a  get  command  (see  get(l))  to  create 

branch  deltas. 

cceil  The  highest  release  (i.e.,  "ceiling"),  a  number  less  than  or  equal  to 
9999,  which  can  be  retrieved  by  a  get  command  for  editing.  The 
default  value  for  an  unspecified  c  flag  is  9999. 

f floor  The  lowest  release  (i.e.,  "floor"),  a  number  greater  than  0  but  less  than 
9999,  which  may  be  retrieved  by  a  get  command  for  editing.  The 
default  value  for  an  unspecified  f  flag  is  1. 

dSID  The  default  delta  number  SID  to  be  used  by  a  get  command  (see 
get(l)). 

istr        Causes  the  message: 

No  id  keywords  (cm7) 

issued  by  get  or  delta  to  be  treated  as  a  fatal  error  (see  delta(l)). 
I  n  the  absence  of  this  flag,  the  message  is  only  a  warning.  The  mes- 
sage is  issued  if  no  SCCS  identification  keywords  (see  get(l))  are 
found  in  the  text  retrieved  or  stored  in  the  SCCS  file.  If  a  value  is 
supplied,  the  keywords  must  exactly  match  the  given  string.  How- 
ever, the  stri  ng  must  contai  n  a  keyword,  but  must  not  contai  n  embed- 
ded newlines. 

j  Allows  concurrent  get  commands  for  editing  on  the  same  SID  of  an 

SCCS  file.  This  allows  multiple  concurrent  updates  to  the  same  ver- 
sion of  the  SCCS  file. 

Only  one  user  can  perform  concurrent  edits.  Access  by  multiple  users 
is  usually  accomplished  by  using  a  common  login  or  a  set  user  ID  pro- 
gram (see  chmod  (1)  and  exec(2)). 

Hist  A  list  of  releases  to  which  deltas  can  no  longer  be  made.  (A  get  -e 
against  one  of  these  locked  releases  fails).  The  list  has  the  following 
syntax: 

list  :  :=  range  |  list  ,  range 
range  ::=  RELEASE  NUMBER   |  a 

The  character  a  in  the  list  is  equivalent  to  specifying  all  releases  for 
the  named  SCCS  file.  Omitting  any  list  is  equivalent  to  a. 

n  Causes  delta  to  create  a  null  delta  in  each  of  those  releases  being 

skipped  (if  any)  when  a  delta  is  made  in  a  new  release  (such  as  when 
making  delta  5.1  after  delta  2.7,  release  3  and  release  4  are  skipped). 
These  null  deltas  serve  as  anchor  points  so  that  branch  deltas  can  be 
created  from  them  later.  The  absence  of  this  flag  causes  skipped 
releases  to  be  nonexistent  in  the  SCCS  file,  preventing  branch  deltas 
from  being  created  from  them  in  the  future. 

qtext  User-definable  text  substituted  for  all  occurrences  of  the  %Q%  keyword 
in  SCCS  file  text  retrieved  by  get. 

mmod  The  module  name  of  the  SCCS  file  substituted  for  all  occurrences  of 
the  %M%  keyword  in  SCCS  file  text  retrieved  by  get.  If  the  m  flag  is 
not  specified,  the  value  assigned  is  the  name  of  the  SCCS  file  with  the 
leading  s .  removed. 

ttype  The  type  of  module  in  the  SCCS  file  substituted  for  all  occurrences  of 
%Y%  keyword  in  SCCS  filetext  retrieved  by  get. 
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v[pgm]  Causes  delta  to  prompt  for  Modification  Request  (MR)  numbers  as 
the  reason  for  creating  a  delta.  The  optional  value  specifies  the  name 
of  a  (MR)  number  validity  checking  program  (see  delta(l)).  (If  this 
flag  is  set  when  creating  an  SCCS  file,  them  option  must  also  be  used 
even  if  its  value  is  null). 

x  Causes  get  to  create  files  with  execute  permissions. 

-d  flag  Causes  removal  (deletion)  of  the  specified  flag  from  an  SCCS  file.  The  -d  option  can 

be  specified  only  when  processing  existing  SCCS  files.  Several  -d  options  can  be  sup- 
plied on  a  singleadmin  command  line.  Seethe-f  option  for  allowableflag  names. 

Hist  A  list  of  releases  to  be  unlocked.  See  the  -f  option  for  a  description 
of  the  1  flag  and  the  syntax  of  a  list. 

-a  login  A  login  name,  or  numerical  HP-UX  group  ID,  to  be  added  to  the  list  of  users  allowed 
to  make  deltas  (changes)  to  the  SCCS  file.  A  group  I D  is  equivalent  to  specifying  all 
login  names  common  to  that  group  ID.  Several  a  options  can  be  used  on  a  single 
admin  command  line.  As  many  logins  or  numerical  group  IDs  as  desired  can  be  on 
the  list  simultaneously.  If  the  list  of  users  is  empty,  anyone  can  add  deltas.  A  login 
or  group  I D  preceded  by  a  !  denies  permission  to  make  deltas. 

-e  login  A  login  name  or  numerical  group  ID  to  be  erased  from  the  list  of  users  allowed  to 
make  deltas  (changes)  to  the  SCCS  file.  Specifyinga  group  ID  is  equivalent  to  specify- 
ing all  login  names  common  to  that  group  I D.  Several  e  options  can  be  used  on  a  sin- 
gle admin  command  line. 

-y[comment]  The  comment  text  is  inserted  into  the  SCCS  file  as  a  comment  for  the  initial  delta  in  a 
manner  identical  to  that  of  delta(l).  Omission  of  the  -y  option  results  in  a  default 
comment  line  being  inserted  in  the  form: 

date  and  time  created  YY  /  MM  /  DD  /  HH  /  MM  /  SS  by  login 

The-y  option  is  valid  only  if  the  -i  and/or  -n  options  are  specified  (i.e.,  a  new  SCCS 
file  is  being  created). 

-m  mrlist  The  list  of  Modification  Request  (MR)  numbers  is  inserted  into  the  SCCS  file  as  the 
reason  for  creating  the  initial  delta,  in  a  manner  identical  to  delta(l).  The  v  flag  must 
be  set  and  the  (MR)  numbers  are  validated  if  the  v  flag  has  a  value  (the  name  of  an 
(MR)  number  validation  program).  Diagnostic  messages  occur  if  the  v  flag  is  not  set 
or  (MR)  validation  fails. 

-h  Causes  admin  to  check  the  structure  of  the  SCCS  file  (see  sccsfile(4)),  and  to  compare 

a  newly  computed  checksum  (the  sum  of  all  of  the  characters  in  the  SCCS  file  except 
those  in  the  first  line)  with  the  checksum  that  is  stored  in  the  first  line  of  the  SCCS 
file.  Appropriate  error  diagnostics  are  produced. 

This  option  inhibits  writing  on  the  file,  thus  canceling  the  effect  of  any  other  options 
supplied,  and  therefore  is  only  meaningful  when  processing  existing  files. 

-z  The  SCCS  file  checksum  is  recomputed  and  stored  in  the  first  line  of  the  SCCS  file 

(see  -h,  above). 

Note  that  use  of  this  option  on  a  truly  corrupted  file  can  prevent  future  detection  of 
the  corruption. 


Access  Control  Lists  (ACLs) 

Do  not  add  optional  ACL  entries  to  SCCS  files.  SCCS  removes  them,  possibly  causing  unexpected  and 
undesirable  access  modes. 


EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single- and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set 
to  the  empty  string,  a  default  of  C  (see  lang(5)j  is  used  instead  of  LANG.  If  any  internationalization  vari- 
able contains  an  invalid  setting,  admin  behaves  as  if  all  internationalization  variables  are  set  to  C.  See 
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envi  ron(5). 

I  nternational  Code  Set  Support 

Single-byte  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Usesccshelp(l)  for  explanations. 

WARNINGS 

SCCS  files  can  beany  length,  but  the  number  of  lines  in  the  text  file  itself  cannot  exceed  99999  lines. 
FILES 

The  last  component  of  all  SCCS  file  names  must  be  of  the  form  s  .filename.  New  SCCS  files  are  given 
mode  444  (see  chmod(l)).  Write  permission  in  the  pertinent  directory  is  required  to  create  a  file.  All  writ- 
ing done  by  admin  is  to  a  temporary  x-file,  called  x.  filename,  (see  get(l)),  created  with  mode  444  if  the 
admin  command  is  creating  a  new  SCCS  file,  or  with  the  same  mode  as  the  SCCS  file  if  it  exists.  After 
successful  execution  of  admin,  the  SCCS  file  is  removed  (if  it  exists),  and  the  x-file  is  renamed  to  the  name 
of  the  SCCS  file.  This  ensures  that  changes  are  made  to  the  SCCS  file  only  if  no  errors  occurred. 

It  is  recommended  that  directories  containing  SCCS  files  be  mode  755  and  that  SCCS  files  themselves  be 
mode  444.  The  mode  of  any  given  directory  allows  only  the  owner  to  modify  SCCS  files  contained  in  that 
directory.  The  mode  of  the  SCCS  files  prevents  any  modification  at  all  except  by  SCCS  commands. 

If  it  should  be  necessary  to  patch  an  SCCS  file  for  any  reason,  the  mode  can  be  changed  to  644  by  the 
owner,  thus  allowing  the  use  of  vi  or  any  other  suitableeditor.  Care  must  betaken!  The  edited  file  should 
always  be  processed  by  an  admin  -h  to  check  for  corruption  followed  by  an  admin  -z  to  generate  a 
proper  checksum.  Another  admin  -h  is  recommended  to  ensure  the  SCCS  file  is  valid. 

admin  also  makes  use  of  a  transient  lock  file  called  z  .filename),  which  is  used  to  prevent  simultaneous 
updates  to  the  SCCS  file  by  different  users.  See  get(l)  for  further  information. 

SEE  ALSO 

delta(l),  ed(l),  get(l),  sccshelp(l),  prs(l),  what(l),  sccsfile(4),  acl(5). 

STANDARDS  CONFORMANCE 

admin:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

answer  -  phone  message  transcription  system 

SYNOPSIS 

answer  [-pu] 

DESCRIPTION 

The  answer  interactive  program  helps  you  to  transcribe  telephone  (and  other)  messages  into  electronic 
mail. 

The  program  uses  your  personal  elm  alias  database  and  the  system  elm  alias  database,  allowing  you  to 
use  al  i  ases  to  address  the  messages. 

Options 

answer  supports  the  foil  owing  options: 

-p    Prompt  for  phone-slip-type  message  fields, 
-u   Allow  addresses  that  are  not  aliases. 

Operation 

answer  begins  with  the  Message  to:  prompt.  Enter  a  one-word  alias  or  a  two-word  user  name 
("Words"  are  separated  by  spaces.)  The  user  name  is  converted  to  an  alias  in  the  form  fjastword,  where  f 
is  the  first  character  of  the  first  word,  lastword  is  the  second  word,  and  all  letters  are  shifted  to  lowercase. 
For  example,  Dave  Smith  isconverted  tothealiasd_smith. 

Without  the  -u  option,  the  specified  or  converted  alias  must  exist  in  the  alias  databases.  With  the  -u 
option,  if  the  processed  "alias"  is  not  in  the  alias  databases,  it  is  used  for  the  address  as  is. 

Thefully  expanded  address  is  displayed. 

With  the-p  option,  you  are  asked  for  typical  message  slip  data: 

Caller: 
of: 

Phone : 
TELEPHONED 

CALLED   TO  SEE  YOU  - 
WANTS   TO  SEE  YOU 
RETURNED   YOUR  CALL  - 
PLEASE  CALL 
WILL  CALL  AGAIN 
*****URGENT******  - 

Enter  the  appropriate  data.  You  can  put  just  an  X  or  nothing  after  the  pertinent  dash  prompts,  or  you  can 
type  longer  comments.  Whatever  you  enter  becomes  part  of  the  message.  Lines  with  no  added  text  are 
omitted  from  the  message. 

Finally,  you  are  prompted  for  a  message.  Enter  a  message,  if  any,  ending  with  a  blank  line.  The  message 
is  sent  and  theMessage  to:  prompt  is  repeated. 

To  end  the  program,  enter  any  one  of  bye,  done,  exit,  or  quit,  at  theMessage  to:  prompt. 

EXAMPLES 

User  input  is  in  normal  type. 

With  No  Options 

This  example  shows  a  valid  alias,  an  invalid  user  name,  and  a  valid  user  name.  I  n  the  invalid  case,  the  con- 
verted alias  is  displayed  in  square  brackets. 


Message  to:  Oswald 

address   'oswaldr@mycompany.com   (Oswald  Rarebit)' 
Enter  message  for  Oswald  ending  with  a  blank  line. 
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>  And  here  is  the  message. 
> 


Message  to:  albert  einstein 

Sorry,  could  not  find  'albert  einstein'  [a_einstein]  in  list! 
Message  to:  johnjones 

address   'mrjones@companybee.com   (John  P.  Jones)' 

Enter  message  for  john  jones  ending  with  a  blank  line. 

>  A  nice  message 
> 


Message  to:  quit 

With  the  -u  Option 

If  you  enter  answer  -u,  the  previous  error  istreated  differently. 

Message  to:  albert  einstein 
address  'a_einstein' 

Enter  message  for  albert  einstein  ending  with  a  blank  line. 

>  About  your  theory  ... 
> 

With  the  -p  Option 

If  you  enter  answer  -p,  the  phone-slip  prompts  are  added.  The  three  lines  with  no  added  text  are 
deleted  from  the  message. 

Message  to:  George  Dancer 

address   'g_dancer@cup.hp.com  (George  B.  Dancer)' 

Caller:  Harold  Maudlin 
of:  Terpsichore  Inc. 

Phone :      123  456  7890 

TELEPHONED  -  at  4:30pm 

CALLED   TO  SEE  YOU  - 

WANTS   TO  SEE  YOU  -  X 

RETURNED   YOUR  CALL  - 

PLEASE  CALL  -  X 
WILL  CALL  AGAIN 

*****Urgent******    -  very  very! 

Enter  message  for  George  Dancer  ending  with  a  blank  line. 

>  He  said  that  you  would  ... 
> 

FILES 

$HOME/  .elm/aliases  User  alias  database  data  table 

$HOME/  .  elm/aliases  .  dir  User  alias  database  directory  table 
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$HOME/ . elm/ aliases . pag 
$HOME/ . elm/aliases . text 
/var/mail/ . elm/aliases 
/var/mail/ . elm/aliases . dir 
/var/mail/ . elm/aliases .pag 
/var/mail/ . elm/aliases . text 
/tmp/snd.  pid 

AUTHOR 

answer  was  developed  by  HP. 

SEE  ALSO 

elm(l),  newalias(l). 


U  ser  al  i  as  database  hash  tabl  e 
User  alias  source  text 
System  alias  database  data  table 
System  alias  database  directory  table 
System  alias  database  hash  table 
System  al  i  as  source  text 
Outbound  mail  message  edit  buffer 
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NAME 

ar  -  create  and  maintain  portable  archives  and  libraries 
SYNOPSIS 

ar  [-]key  [-][modifier  ...]  [posname]  afile  [name  ...] 
DESCRIPTION 

Thear  command  maintains  groups  of  files  combined  into  a  single  archive  file.  Its  main  use  is  to  create  and 
update  library  files  as  used  by  the  link  editor  (see  I d (1)).  It  can  be  used,  however,  for  any  similar  purpose. 
The  magic  string  and  file  headers  used  by  ar  consist  of  printable  ASCI  I  characters.  If  an  archive  is  com- 
posed of  printablefiles,  the  entire  archive  is  printable. 

Individual  files  are  inserted  without  conversion  into  the  archive  file.  When  ar  creates  an  archive,  it 
creates  headers  in  a  format  that  is  portable  across  all  machines.  See  ar(4)  for  a  detailed  description  of  the 
portable  archive  format  and  structure.  The  archive  symbol  table  (described  in  ar(4))  is  used  by  the  link  edi- 
tor to  search  repeatedly  and  efficiently  through  libraries  of  object  files.  An  archive  symbol  table  is  created 
and  maintained  by  ar  only  when  the  archive  contains  at  least  one  object  file.  The  archive  symbol  table  is 
in  a  specially  named  file  that  is  always  the  first  file  in  the  archive.  This  file  is  never  mentioned  or  accessi- 
ble to  the  user.  Whenever  ar  is  used  to  create  or  update  the  contents  of  an  archive,  the  symbol  table  is 
rebuilt  (unless  the  z  modifier  is  used).  The  s  modifier  described  below  forces  the  symbol  table  to  be  rebuilt. 

One  key  operation  character  from  the  set,  drqtpmx,  is  required  and  can  be  optionally  preceded  by  a 
hyphen  (-).  The  required  key  operation  character  can  be  specified  with  one  or  more  modifier  characters 
from  the  set  abcfFilsuvzACT.  posname  is  used  with  the  r  and  m  key  operations  and  the  a,  b,  and  i 
modifiers  to  specify  a  position  in  the  archive,  afile  is  the  archive  file.  Constituent  files  in  the  archive  file 
are  specified  by  name  arguments. 

Thefollowing  list  describes  the  key  operation  characters: 

d     Delete  the  named  files  from  the  archive  file. 

r     Replace  the  named  files,  or  add  a  new  file  to  the  archive: 

•  If  the  u  modifier  is  used  with  the  operation  character  r,  only  those  files  with  modification 
dates  later  than  those  of  the  corresponding  member  files  are  replaced. 

•  If  an  optional  positioning  character  from  the  set  abi  is  used,  the  posname  argument  must  be 
present  and  specifies  that  new  files  are  to  be  placed  after  (a)  or  before  (b  or  i)  posname.  I  n 
the  absence  of  a  positioning  character,  new  files  are  placed  at  the  end. 

•  ar  creates  afile  if  it  does  not  already  exist. 

•  If  no  nameis specified  and: 

•  the  specified  archive  file  does  not  exist,  ar  creates  an  empty  archive  file  containing  only 
the  archive  header  (see  ar(4)). 

•  the  archive  contains  one  or  more  files  whose  names  match  names  in  the  current  directory, 
each  matching  archive  file  is  replaced  by  the  corresponding  local  file  without  considering 
which  file  may  be  newer  unless  the  u  modifier  is  also  specified. 

q  Quickly  append  the  named  files  to  the  end  of  the  archive  file.  Positioning  characters  are  invalid. 
The  operation  does  not  check  to  determine  whether  the  added  members  are  already  in  the 
archive,  ar  creates  afile  if  it  does  not  already  exist. 

t  Print  a  table  of  contents  of  the  archive  file  to  the  standard  output.  If  no  names  are  given,  all 
files  in  the  archive  are  described.  If  names  are  given,  information  about  only  those  files  appears. 

p  Print  the  named  files  in  the  archive  to  the  standard  output.  If  no  names  are  specified,  the  con- 
tents of  all  files  are  printed  in  the  order  that  they  appear  in  the  archive. 

m  Move  the  named  files.  By  default,  the  files  are  moved  to  the  end  of  the  archive.  If  a  positioning 
character  is  present,  the  posname  argument  must  be  present  and,  as  in  the  r  operation, 
posname  specifies  where  the  files  are  to  be  moved.  Note  that,  when  used  with  a  positioning  char- 
acter, the  files  are  moved  in  the  same  order  that  they  currently  appear  in  the  archive,  not  in  the 
order  specified  on  the  command  line.  See  EXAMPLES. 

x  Extract  the  named  files.  If  no  names  are  given,  all  files  in  the  archive  are  extracted.  In  neither 
case  does  x  alter  entries  from  the  archive  file. 
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Thefollowing  list  describes  the  optional  modifier  characters: 

a     Position  the  files  after  the  existing  positioning  file  specified  by  posname . 

b     PI  ace  the  new  files  before  the  existing  positioning  file  specified  by  posname . 

c  Suppress  the  message  normally  produced  when  afile  is  created.  For  r  and  q  operations,  ar  nor- 
mally creates  afileif  it  does  not  already  exist. 

f  Truncate  the  named  file  names  to  14  bytes  before  performing  operations  on  an  archive.  This 
modifier  has  been  provided  for  compatibility  with  previous  releases  where  file  names  up  to  a 
maximum  of  14  bytes  were  supported.  Longer  file  names  were  truncated.  When  used  with  the  r 
operation,  the  first  existing  file  that  matches  the  truncated  file  name  is  replaced.  The  f  modifier 
can  also  be  used  with  other  operations  to  allow  the  full  file  names  to  be  specified,  rather  than  the 
truncated  filenames.  Also  see  the  description  of  the  F  modifier. 

i  Place  the  new  files  before  the  existing  positioning  file  specified  by  posname  .  Identical  to  the  b 
modifier. 

1  PI  ace  temporary  files  in  the  local  current  working  directory  rather  than  in  the  directory  specified 
by  the  environment  variable  TMPDIR  or  in  the  default  directory  /var/tmp.  Only  the  d,  m,  q, 
and  r  operations  and  the  s  and  F  modifiers  use  temporary  files. 

s  Regenerate  the  archive  symbol  table  even  if  ar  is  not  invoked  with  an  operation  that  modifies 
the  archive  contents.  This  modifier  is  useful  for  restoring  the  archive  symbol  table  after  the 
strip  command  has  been  used  on  the  archive  (see  strip(l))  or  after  the  archive  has  been 
modified  using  the  z  modifier. 

u  Update  the  archive,  (r  operations  only)  Do  not  copy  the  local  file  to  the  archive  unless  the  local 
file  is  newer  than  the  corresponding  existing  file  in  the  archive. 

v  Give  a  verbose  file-by-file  description  of  the  creation  or  modification  of  an  archive  file  to  the  stan- 
dard output.  When  used  with  t,  v  gives  a  long  listing  of  all  information  about  the  files.  When 
used  with  the  d,  m,  p,  q,  or  x  operations,  the  verbose  modifier  causes  ar  to  print  each  key  opera- 
tion character  and  the  file  name  associated  with  that  operation.  For  the  r  operation,  ar  shows 
an  a  if  it  adds  a  new  file  or  an  r  if  it  replaces  an  existing  one.  For  thep  operation,  ar  prints  the 
name  of  the  file  to  the  standard  output  before  the  contents  of  the  file  are  printed. 

z  Suppress  the  rebuilding  of  the  symbol  table  when  the  archive  is  modified.  This  modifier  is  useful 
only  to  avoid  long  build  times  when  creating  a  large  archive  piece-by-piece.  If  an  existing  archive 
contains  a  symbol  table,  the  z  modifier  will  cause  it  to  be  invalidated.  If  a  file  name  longer  than 
15  bytes  is  given  the  entire  archive  is  rewritten.  To  rebuild  the  symbol  table,  either  use  the 
ranlib  command  (see ranlib(l)),  or  invokear  again  with  thes  modifier. 

A  Suppress  warning  messages  regarding  optional  access  control  list  entries,  ar  does  not  archive 
optional  access  control  list  entries  in  a  file's  access  control  list  (see  acl(5)).  Normally,  a  warning 
message  is  printed  for  each  file  having  optional  access  control  list  entries. 

C  Prevent  extracted  files  from  replacing  files  with  the  same  name.  The  C  modifier  can  only  be 
used  with  thex  operation. 

F  Truncate  the  entire  archive.  The  F  modifier  causes  the  entire  archive  to  be  rewritten  such  that 
all  file  names  within  the  archive  are  truncated  to  14  bytes,  even  when  ar  does  not  modify  the 
archive  contents.  The  long  name  table  will  be  removed  (see  ar(4)).  This  modifier  has  been  pro- 
vided for  compatibility  with  previous  releases  where  file  names  up  to  a  maximum  of  14  bytes 
were  supported.  Also  see  the  description  of  the  f  modifier. 

T  Truncate  file  names  whose  archive  names  are  longer  than  those  supported  by  the  file  system.  By 
default,  files  with  names  longer  than  those  supported  by  the  file  system  will  not  be  extracted  and 
will  causean  error.  TheT  modifier  can  only  be  used  with  thex  operation. 

Only  the  following  combinations  are  meaningful;  no  other  combination  of  modifiers  with  operations  have 
any  effect  on  the  operation: 


d: 

V, 

f,  F,  1 

m: 

V, 

f,  F,  1,  and  a  | 

bl  i 

r: 

V, 

f ,  F,  1,  c,  A,  u, 

and  a  |   b  |  i 

q: 

V, 

f ,  F,  1,  c,  A,  z, 

s 

t: 

V, 

f ,  F,  s 
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p:     v,  f ,  F,  s 

x:     v,  f ,  F,  s,  C,  T 

EXTERNAL  INFLUENCES 
Environment  Variables 

The  foil  owing  internationalization  variables  affect  the  execution  of  ar: 

LANG 

Determines  the  locale  category  for  native  language,  local  customs  and  coded  character  set  in  the 
absence  of  LC_ALL  and  other  LC_*  environment  variables.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of  LANG. 

LC_ALL 

Determines  the  values  for  all  locale  categories  and  has  precedence  over  LANG  and  other  LC_* 
environment  variables. 

LC_CTYPE 

Determines  the  locale  category  for  character  handlingfunctions. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic  messages 
written  to  standard  error. 

LC_NUMERIC 

Determines  the  locale  category  for  numeric  formatting. 

LC_TIME 

Determines  the  format  and  contents  of  date  and  time  formatting. 

NLSPATH 

Determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

If  any  internationalization  variable  contains  an  invalid  setting,  ar  behaves  as  if  all  internationalization 
variables  are  set  toe.  See  environ  (5). 

I  n  addition,  the  foil  owing  environment  variable  affects  ar: 

TMPDIR 

Specifies  a  directory  for  temporary  files  (see  tmpnam(3S)).  The  1  modifier  overrides  the  TMPDIR 
variable,  and  TMPDIR  overrides  /var/tmp,  the  default  directory. 

DIAGNOSTICS 

phase  error  on  filename 

The  named  file  was  modified  by  another  process  while  ar  was  copying  it  into  the  archive. 
When  this  happens,  ar  exits  and  the  original  archive  is  left  untouched. 

ar  write  error:    file  system  error  message 

ar  could  not  write  to  a  temporary  file  or  the  final  output  file.  If  ar  was  trying  to  write  the 
final  output  file,  the  original  archive  is  lost. 

ar  reports  cannot  create  file,  a,  where  file. a  is  an  ar-format  archive  file,  even  if  file,  a  already 
exists.  This  message  is  triggered  when  file,  a  is  write-protected  or  inaccessible. 

EXAMPLES 

Create  a  new  file  (if  one  does  not  already  exist)  in  archive  format  with  its  constituents  entered  in  the  order 
indicated: 

ar  r  newlib.a  f3  f2  fl  f4 

Replace  files  f  2  and  f  3  such  that  the  new  copies  follow  file  f  1,  and  f  3  follows  f  2: 

ar  ma  f  1  newlib .a  f 2  f 3 
ar  ma  f 2  newlib . a  f 3 
ar  r  newlib .a  f 2  f 3 

The  archive  is  then  ordered: 

newlib.a:      fl  f2'    f3'  f4 

where  the  single  quote  marks  indicate  updated  files.  The  first  command  says  "move  f  2  and  f3  after  fl  in 
newlib.a",  thus  creating  the  order: 
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fl  f3  f2  f4 

Note  that  the  relative  order  of  f  2  and  f  3  has  not  changed.  The  second  command  says  "move  f  3  after  f  2 
in  newlib.a",  creating  the  order: 

fl  f2  f3  f4 

The  third  command  then  replaces  files  f2  and  f3.  Since  files  f2  and  f3  both  already  existed  in  the 
archive,  this  sequence  of  commands  could  not  be  simply  replaced  by: 

ar  ra  f 1  newlib .a  f 2  f 3 

because  the  previous  position  and  relative  order  of  f  2  and  f  3  in  the  archive  are  preserved  (no  matter  how 
the  files  are  specified  on  the  command  line),  producing  the  foil  owing  archive: 

newlib.a:      f3'    f2'    fl  f4 


WARNINGS 

If  you  are  a  user  who  has  appropriate  privileges,  ar  can  alter  any  archive  file,  even  if  it  is  write-protected. 

If  the  same  file  is  mentioned  twice  in  an  argument  list,  it  might  be  put  in  the  archive  twice. 

If  multiple  copies  of  a  file  exist  in  an  archive,  ar  matches  the  first  occurrence  of  the  file  in  the  archive. 

ar  automatically  creates  an  archive  symbol  table,  a  task  performed  in  early  HP-UX  versions  by  ranlib. 
Use  of  the  z  modifier  either  suppresses  generation  of  the  symbol  table,  or  invalidates  it  if  it  exists.  The 
ranlib  command  can  be  used  to  rebuild  the  symbol  table  if  an  archive  was  built  with  the  z  modifier. 


FILES 

/var/tmp/ar*  Temporary  files 

SEE  ALSO 

System  Tools: 

I d (1)  I  nvoke  the  link  editor 


Miscellaneous: 


acl(5)  Access  control  lists 

a.out(4)  Assembler,  compiler,  and  linker  output 

ar(4)  Archive  format 

lorder(l)  Find  the  ordering  relation  for  object  files  or  archive  libraries 

ranlib(l)  Regenerate  an  archivesymbol  table 

strip(l)  Strip  symbol  and  line  number  information  from  an  object  file 

tmpnam(3S)  Create  a  name  for  a  temporary  file 


Texts  and  Tutorials: 

HP-UX  Linker  and  Libraries  Online  User  Guide 

(Seethe+help  option) 
HP-UX  Linker  and  Libraries  User's  Guide 

(See  manuals(5)  for  ordering  information) 

STANDARDS  CONFORMANCE 

ar:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

as  -  assembler  (Precision  Architecture) 

SYNOPSIS 

as  [[option]...  [file]  ...  ]... 

DESCRIPTION 

The  as  command  assembles  source  text  from  files  or  standard  input  and  produces  a  relocatable  object  file 
suitablefor  the  link  editor,  Id  (see  I d (1). 

Source  text  is  read  from  standard  input  only  if  no  file  argument  is  given.  Standard  input  cannot  be  a  device 
file,  such  as  a  terminal.  The  option  and  file  arguments  can  be  intermingled  on  the  command  line.  Every 
specified  option  applies  to  every  specified  file,  or  standard  input.  The  source  files  are  concatenated  to  form 
a  single  input  stream. 

If  the  -o  objfile  option  is  not  specified,  the  .  s  suffix  (if  any)  is  stripped  from  the  end  of  the  last  source  file 
name  and  .  o  is  appended  to  the  name  to  form  the  name  of  the  default  object  code  output  file. 

as  output  is  not  optimized,  as  creates  a  relocatable  object  file  that  must  be  processed  by  Id  before  it  can 
be  successfully  executed  (seeld(l)). 

The  cc  compiler  normally  runs  the  C  preprocessor  cpp  (see  cpp(l)),  then  invokes  as  to  assemble  the  .  s 
files  together  with  /usr/lib/pcc_pref  ix .  s,  and  subsequently  invokes  Id. 

Arguments 

as  recognizes  the  following  arguments. 

fi  I e  A  text  fil e  contai  n  assembl er  source  code, 

option  An  option  described  below  in  Options. 

Options 

as  recognizes  the  following  values  for  the  option  argument. 

-e  Permit  an  unlimited  number  of  errors  to  be  tolerated  before  the  assembly  process  is 

abandoned.  By  default,  one  hundred  errors  are  allowed  before  the  assembler 
aborts. 

-f  Set  the  default  value  for  the  .  CALLINFO  directive  to  CALLS,  The  normal  default 

value  for  a  .CALLINFO  that  omits  the  CALLER,  CALLS  orNO_CALLS  parameter 

isNO_CALLS. 

-1  Write  a  listing  of  the  program  to  standard  output  after  assembly.  This  listing  shows 

the  offsets  of  instructions  and  actual  values  for  fields. 

-o  objfile  Name  the  output  object  file  objfile  instead  of  using  the  default  .  o  suffix  on  the  file 

name  of  the  last  file  specified. 

-p  number  Set  the  default  privilege  level  for  an  .  EXPORT  directive  to  number.  By  default,  all 
user-level  procedures  are  exported  at  privilege  level  3. 

-s  Set  the  output  file  suffix  to  .  ss  instead  of  .o.  The  file  will  have  a  format  suitable 

for  conversion  to  the  ROM  burning  programs. 

-u  Do  not  create  unwind  descriptors.  To  avoid  the  need  for  the  .CALLINFO  directive, 

the  .ENTER  and  .LEAVE  directives  must  not  have  been  used. 

-v  xrfile  Write  cross-reference  data  to  the  file  named  xrfile. 

-V  Print  the  version  number  of  the  assembler  program  to  standard  error  before  assem- 

bling the  source  text. 

-w[number]  Either  suppress  all  warning  messages  if  no  number  is  supplied  or  suppress  just  the 
warning  number  provided.  Multiple  -wnumber  options  can  be  used  to  suppress 
additional  warning  messages. 

-HDAarchitecture  Assemble  code  for  the  architecture  specified.  The  use  of  this  option  is  discouraged. 

The  preferred  method  for  selecting  the  architecture  is  to  have  a  .LEVEL  directive 
contained  within  the  assembly  source  file. 
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The  assembler  uses  the  foil  owing  precedence  to  determine  the  target  architecture. 

1.  Use  the  .LEVEL  directive  within  the  assembly  source  file. 

2.  Usethe+DA  command-linespecification. 

3.  Use  the  default  architecture  of  PA_RISC_1 . 0  . 

+z,  +Z  Both  of  these  options  are  used  in  the  building  of  shared  libraries.  For  a  more  com- 

plete discussion  regarding  these  options,  see  the  manual  HP-UX  Linker  and 
Libraries  User's  Guide. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

DIAGNOSTICS 

When  syntactic  or  semantic  errors  occur,  a  single-line  diagnostic  is  written  to  standard  error,  that  includes 
the  file  name  and  the  line  number  where  it  occurred.  The  format  is  as  follows: 

as:  "filename' , line  line:  error  error:  message 
source  =  source-line 

WARNINGS 

as  does  not  invoke  cpp(l)  or  m4(l)  to  perform  macro  processing. 
FILES 

/usr/include/hard_reg.hr         Hardware  register  definitions 
/usr/include/soft_reg.h  Software  calling  convention  register  definitions 

/usr/include/std_space.h         Standard  space  and  subspace  definition 
/usr/lib/nls/msg/C/as  .  cat       Assembler  error  message  catalog 
/usr/lib/pcc_prefix.  s  Space,  subspaceand  register  definitions 

file.o  Object  file 

SEE  ALSO 

adb(l),  cc  bundled(l),  ld(l),  nm(l),  crt0(3). 

Assembly  LanguageReferenceManual, 

Precision  Architecture  and  Instruction  Reference  Manual, 

Procedure  Calling  Conventions  Reference  Manual . 
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NAME 

asa  -  interpret  ASA  carriage  control  characters 

SYNOPSIS 

asa  [files] 

DESCRIPTION 

asa  interprets  the  output  of  FORTRAN  programs  that  utilize  ASA  carriage  control  characters.  It 
processes  either  the  files  whose  names  are  given  as  arguments,  or  the  standard  input  if  -  is  specified  or  if 
no  file  names  are  given.  Thefirst  character  of  each  lineisassumedtobea  control  character.  Thefollowing 
control  characters  are  interpreted  as  indicated: 

(blank)  Output  a  single  new-line  character  before  printing. 

(space)  (XPG4only.)  Therest  of  the  linewill  beoutput  without  change. 

0         Output  two  new-line  characters  before  printing. 

0  (XPG4only.)  A  <newline> shall  beoutput,  then  therest  of  theinput  line. 

1  Output  a  new-page  character  before  printing. 
+         Overprint  previous  line. 

+  (XPG4  only.)  The  <newline>  of  the  previous  line  shall  be  replaced  with  one  or  more 
implementaions-defined  characters  that  causes  printing  to  return  to  column  position  1,  fol- 
lowed by  the  rest  of  the  input  line.  If  the  +  is  the  first  character  in  the  input,  it  shall  have  the 
same  effect  as  <space>. 

Lines  beginning  with  other  than  the  above  characters  are  treated  the  same  as  lines  beginning  with  a  blank. 
The  first  character  of  a  line  is  not  printed.  If  any  such  lines  appear,  an  appropriate  diagnostic  is  sent  to 
standard  error.  This  program  forces  thefirst  line  of  each  input  file  to  start  on  a  new  page. 

(XPG4  only.)  The  action  of  the  asa  utility  is  unspecified  upon  encountering  any  character  other  than  those 
listed  above  as  the  first  character  in  a  line. 

To  view  the  output  of  FORTRAN  programs  which  use  ASA  carriage  control  characters  and  have  them 
appear  in  normal  form,  asa  can  be  used  as  a  filter: 

a .  out    |  asa   |  lp 

The  output,  properly  formatted  and  paginated,  is  then  directed  to  the  line  printer.  FORTRAN  output  pre- 
viously sent  to  a  file  can  be  viewed  on  a  user  terminal  screen  by  using: 

asa  file 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  within  file  as  single- and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  asa  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 


SEE  ALSO 

efl(l),  f77(l),  fsplit(l),  ratfor(l). 

STANDARDS  CONFORMANCE 

asa:  XPG4,  POSIX.2 
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NAME 

at,  batch  -  execute  batched  commands  immediately  or  at  a  later  time 
SYNOPSIS 

Enter  commands  from  standard  input  to  run  at  a  specified  time: 

at  [-m]  [-q  queue]  -t  spectime 

commands 

eof 

at  [-m]  [-q  queue]  time  [date]  [next  timeunit  |  +count  timeunit] 

commands 

eof 

Enter  commands  from  a  file  to  run  at  a  specified  time: 

at  -f  job-file  [-m]  [-q  queue]  -t  spectime 

at  -f  job-file  [-m]  [-q  queue]  time  [date]  [next  timeunit  |  +count  timeunit] 

List  scheduled  jobs: 

at  -d  job-id  ... 

at  -1  [job-id  ...] 
at  -1  -q  queue 

Cancel  (remove)  a  scheduled  job: 

at  -r  job-id  ... 

Enter  commands  from  standard  input  to  run  as  a  batch  process: 

batch 

commands 
eof 

Enter  commands  from  a  file  to  run  as  a  batch  process: 

batch  <  job-file 

DESCRIPTION 

Theat  and  batch  commands  schedulejobs  for  execution  bythecron  daemon  (see  cron(lM)). 

at  schedules  a  job  for  execution  at  a  specified  time,  at  can  also  list  (-1)  or  remove  (-r)  existing 
scheduled  at  and  batch  jobs. 

batch  schedules  a  job  for  execution  immediately,  or  as  soon  as  system  load  levels  permit. 
You  can  enter  commands  into  a  job  in  one  of  the  foil  owing  ways: 

•  From  the  keyboard  on  separate  lines  immediately  after  the  at  or  batch  command  line,  followed  by 
the  currently  defined  eof  (end-of-file)  character  to  end  the  input.  The  default  eof  is  Ctrl-D.  It  can  be 
redefined  in  your  environment  (see  stty(l)). 

•  With  the  -f  option  of  the  at  command  to  read  input  from  a  script  file. 

•  From  output  piped  from  a  preceding  command. 

Options  and  Arguments 

at  recognizes  the  following  options  and  arguments. 


commands 

One  or  more  HP-UX  commands  that  can  be  executed  as  a  shell  script  by  at  or 

batch. 

eof 

End-of-file  character.  The  default  is  Ctrl-D  unless  defined  otherwise  in  your 

environment. 

job-file 

The  path  name  of  an  existing  file. 

job-id 

The  job  identifier  reported  by  at  or  batch  when  the  job  was  originally 

scheduled. 

-d  job-id  ... 

Displays  the  contents  of  the  specified  job.  An  unprivileged  user  is  restricted  to 

display  information  only  on  jobs  that  the  user  owns.  A  user  with  the  appropriate 
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privileges  is  ableto  display  information  about  all  jobs. 

-f  job-file  Read  in  the  commands  contained  in  job-file  instead  of  using  standard  input. 

-1  [job-id  ...]         List  thejobs  specified.  If  nojob-ids  are  given,  all  jobs  are  listed. 

-m  Send  mail  to  the  invoking  user  after  the  job  has  run,  announcing  its  completion. 

Unless  redirected  elsewhere  within  thejob,  standard  output  and  standard  error 
produced  by  thejob  are  automatically  mailed  to  the  user  as  well. 

-q  queue  Submit  the  specified  job  to  the  queue  indicated  (see  queuedefs(4)).  Queues  a,  b, 

and  d  through  y  can  be  used,  at  uses  queue  a  by  default,  batch  always  uses 
queue b.  All  queues  except  b  require  a  time  or  a  -t  specification,  at  -qb  is 
equ  i  va  I  ent  to  bat  ch . 

-r  job-id  ...  Remove  thejobs  specified  by  each  job-id. 

-t  spectime  Definetheabsolutetimetostartthejob. 

spectime  A  date  and  time  in  the  format: 

[[CC]YY]MMDDhhmm  [  .  ss  ] 

where  the  decimal  digit  pairs  are  as  follows: 

CC   Thefirst  twodigitsof  theyear  (19,  20). 

YY    The  second  twodigitsof  theyear  (69-99,  00-68).  See  WARN- 
INGS. 

MM  The  month  of  theyear  (01-12). 
DD  Theday  of  the  month  (01-31). 
hh    The  hour  of  theday  (00-23). 
mm  The  minute  of  the  hour  (00-59). 
ss    The  second  of  the  minute  (00-61). 

If  both  CC  and  YY  are  omitted,  the  default  is  the  current  year. 

If  CC  is  omitted  and  YY  is  in  the  range  69-99,  CC  defaults  to  19. 
Otherwise,  CC  defaults  to  20. 

The  range  for  ss  provides  for  two  leap  seconds.  If  ss  is  60  or  61,  and 
the  resulting  time,  as  affected  by  the  TZ  environment  variable,  does 
not  refer  to  a  leap  second,  the  time  is  set  to  the  whole  minute  follow- 
ing mm. 

If  ss  is  omitted,  it  defaults  to  00. 

time  [date]  Define  the  base  time  for  starting  thejob. 

time  A  time  specified  as  one,  two,  or  four  digits.  One-  and  two-digit 
numbers  represent  hours;  four  digits  represent  hours  and  minutes. 

Alternately,  time  can  be  specified  as  two  numbers  separated  by  a 
colon  (: ),  a  single  quote  (' ),  the  letter  h  (h),  a  period  (. ),  or  a  comma 
(,).  Spaces  may  be  present  between  the  separator  and  digits 
representing  minutes.  If  defined  in  langinfo(5),  special  time  unit 
characters  can  be  used. 

am  or  pm  can  be  appended  to  indicate  morning  or  afternoon.  Other- 
wise, a  24-hour  clock  is  understood.  For  example,  0815,  8:15, 
8'  15,  8hl5,  8 . 15,  and  8, 15  are  read  as  15  minutes  after  eight  in 
the  morning.  The  suffixes  zulu  and  utc  can  be  used  to  specify  Coor- 
dinated Universal  Time  (UTC),  equivalent  to  Greenwich  Mean  Time 
(GMT). 

The  special  names  midnight,  noon,  and  now  are  also  recognized. 

date  A  day  of  the  week  (fully  spelled  out  or  abbreviated)  or  a  date  consist- 
ing of  a  day,  a  month,  and  optionally  a  year.  The  day  and  year  fields 
must  be  numeric,  and  the  month  can  be  either  fully  spelled  out,  abbre- 
viated, or  numeric.  The  fields  in  the  date  string  are  separated  by 
punctuation  marks  such  as  slash  (/),  hyphen  (-),  period  (.),  and 
comma  (, ).  If  defined  in  langinfo(5),  special  date  unit  characters  can 
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be  present.  A  field  having  a  value  greater  than  31  is  treated  as  the 
year  field  and  the  remaining  two  fields  in  the  date  string  are  treated 
as  month  and  day  fields.  Otherwise,  if  a  given  date  is  ambiguous  (such 
as2/5  or  2/5/10),  the D_T_FMT  string  (if  defined  in  langinfo(5))  is 
used  to  resolve  the  ambiguity. 

Two  special  days,  today  and  tomorrow,  are  also  recognized.  If  no 
date  is  given,  today  is  assumed  if  the  given  time  is  greater  than  the 
current  time;  tomorrow  is  assumed  if  it  is  less. 

If  the  given  month  is  less  than  the  current  month  (and  no  year  is 
given),  next  year  is  assumed.  Two-digit  years  in  the  range  69  to  99 
are  expanded  to  1969  to  1999;  in  the  range  00  to  68,  to  2000  to  2068. 

nexttimeunit  |    +  count  timeunit 

Delay  the  execution  date  and  time  by  a  specific  number  of  time  units  after  the 
basetime  specified  by  time  [date]. 

count       A  decimal  number,  next  is  equivalent  to +1. 

timeunit  A  time  unit,  one  of  the  following:  minutes,  hours,  days,  weeks, 
months,  or  years,  or  their  singular  forms. 

How  J  obs  Are  Processed 

When  a  job  is  accepted,  at  and  batch  printa  message  to  standard  error  intheform: 

job  job-id  at  execution-date 

where  job-id  is  the  job  identifier  in  the  form  jobnumber .  queue,  such  as  756284400. a,  and  execution-date 
is  the  date  and  time  when  the  job  will  be  released  for  execution. 

If  your  login  shell  is  not  the  POSIX  shell  (/usr/bin/sh),  the  commands  also  print  a  warning  message: 

warning:    commands  will  be  executed  using  /usr/bin/sh 
at  jobs  default  to  queue  a.  batch  jobs  always  go  in  queueb.  Seethe  -q  option. 

An  at  or  batch  job  consists  of  a  two-part  script  stored  in  /var/spool/cron/at  jobs  that  can  be 
executed  by  the  POSIX  shell. 

The  first  part  sets  up  the  environment  to  match  the  environment  when  the  at  or  batch  command  was 
issued.  Thisincludes  the  current  shell  environment  variables,  current  directory,  umask,  andulimit  (see 
ulimit(2),  umask(l),  and  proto(4)).  Open  file  descriptors,  traps,  and  priority  are  lost. 

The  second  part  consists  of  the  commands  that  you  entered. 

When  cron  dispatches  the  job,  it  starts  a  POSIX  shell  to  execute  the  script. 

The  number  of  jobs  executing  from  a  queue  at  any  time  is  controlled  by  parameters  in  the  file 
/var/adm/cron/queuedef  s  (see  queuedefs(4)). 

Standard  output  and  standard  error  from  the  job  are  mailed  to  the  user  unless  they  are  redirected  else- 
where within  the  job. 

Scheduled  jobs  are  immuneto  the  SIGHUP  hangup  signal,  and  remain  scheduled  if  the  user  logs  off. 

Users  are  permitted  to  use  the  at  and  batch  commands  if  their  user  names  appear  in  the  file 
/usr/lib/cron/at .  allow.  If  that  file  does  not  exist,  users  can  use  at  and  batch  if  their  names  do 
not  appear  in  the  file  /usr/lib/cron/at .  deny.  If  neither  file  exists,  only  superuser  is  allowed  to 
submit  jobs.  If  only  at  .deny  exists  but  is  empty,  all  users  can  use  at  and  batch.  The  allow/deny 
files  consist  of  one  user  name  per  line. 

All  users  can  list  and  remove  their  own  jobs.  Users  with  appropriate  privileges  can  list  and  remove  jobs 
other  than  their  own. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_TIME  determines  the  format  and  contents  of  date  and  time  strings. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 
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LC_ME  S  SAGE  S  also  determines  the  languagein  which  the  words  days,  hours,  midnight,  minutes, 
months,  next,  noon,  now,  today,  tomorrow,  weeks,  years,  and  their  singular  forms  can  also  be 
specified. 

IF  LC_TIME  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set 
to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  all  internationalization  variables  default  to 
"C"  (see environ (5)). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

The  exit  code  is  set  to  one  of  the  following: 

0  Successful  completion 

1  Failure 

DIAGNOSTICS 

at  produces  self-explanatory  messages  for  syntax  errors  and  out-of-range  times. 

warning:    commands  will  be  executed  using  /usr/bin/sh 

If  your  login  shell  is  not  the  POSIX  shell  (/usr/bin/sh),  at  and  batch  produce  a  warning  mes- 
sage asa  reminder  that  at  and  batch  jobs  are  executed  using /usr/bin/sh. 

EXAMPLES 

Thefollowing  commands  show  three  different  ways  to  run  a  POSIX  shell  script  file  named  delayed- job 
five  minutes  from  now: 

at  -f  delayed- job  now  +  5  minutes 
cat  delayed- job    |   at  now  +  5  minutes 
at  now  +  5  minutes  <delayed-job 

Run  a  typical  HP-UX  command  (nroff  in  thiscase)  when  system  load  levels  permit,  and  redirect  standard 
output  and  standard  error  to  files: 

batch 

nroff  source-file   >output-file  2>error-file 

eof       (the  default  is  Ctrl-D) 

Run  a  job  contained  in  future  in  the  home  directory  at  12:20  a.m.  on  December  27,  2013: 

at  -f  $HOME/future  -t201312271220 . 00 

Redirect  standard  error  to  a  pipe  (useful  in  a  shell  procedure).  Note  that  the  sequence  of  the  output 
redirection  specifications  is  significant.  Standard  error  is  redirected  to  where  standard  output  is  going; 
standard  output  is  redirected  to  a  file;  the  original  "standard  output"  (which  now  consists  of  the  former 
standard  error)  is  piped  to  the  mail  program. 

batch  «  !  !       (sets  eof  temporarily  to  !  ! ) 

nroff  input-file  2>&1  1>  output-file    |  mail  loginid 
!  i 

Run  a  job  contained  in  jobfile  in  the  home  directory  at  5:00  a.m.  next  Tuesday: 

at  -f  $HOME/ jobfile  5am  tuesday  next  week 
Run  the  same  job  at  5:00  a.m.  one  week  from  next  Tuesday  (i.e.,  2  Tuesdays  in  advance): 

at  -f  $HOME/ jobfile  5am  tuesday  +  2  weeks 

Add  a  command  to  the  file  named  weekly-run  in  directory  jobs  in  the  home  directory  so  that  it 
automatically  reschedules  itself  every  time  it  runs.  This  example  reschedules  itself  every  Thursday  at  1900 
(7:00  p.m.): 

echo  "sh  $HOME/ jobs/weekly-run"    |   at  1900  thursday  next  week 

Thefollowing  commands  show  several  forms  recognized  by  at  and  include  native  language  usage: 
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at  0815  Jan  24 

at  8:15  Jan  24 

at  9:30am  tomorrow 

at  now  +  1  day 

at  -f  job  5  pm  Friday 

at  17:40  Tor. 

at  17h46  demain 

at  5:30  26.   Feb.  1988 

at  12:00  26-02 


#  in  Danish 

#  in  French 

#  in  German 

#  in  Finnish 


WARNINGS 

If  the  date  argument  begins  with  a  number  and  the  time  argument  is  also  numeric  without  a  suffix,  the 
timeargument  should  bea  four-digit  number  that  can  be  correctly  interpreted  as  hours  and  minutes. 

If  you  use  both  next  and  +count  within  a  single  at  command,  the  first  operator  is  accepted  and  the  trail- 
ing operator  is  silently  ignored. 

If  you  use  both  -t  and  time  ...  in  the  same  command,  the  first  specified  is  accepted  and  the  second  is 
silently  ignored. 

If  the  FIFO  used  to  communicate  with  cron  fills  up,  at  is  suspended  until  cron  has  read  sufficient  mes- 
sages from  the  Fl  FO  to  make  room  for  the  message  at  is  trying  to  write.  This  condition  can  occur  if  at  is 
writing  messages  faster  than  cron  can  process  them  or  if  cron  is  not  executing. 

Scheduled  processes  are  run  in  the  background.  Any  script  file  that  calls  itself  will  cause  the  user  or  the 
system  to  run  out  of  avail  able  processes. 

If  the  execution-time  request  for  a  job  duplicates  the  execution  time  of  a  currently  scheduled  job,  the  new 
job  time  is  set  to  the  next  availablesecond. 

at  will  not  schedulejobs  whose  start  time  precedes  the  current  Epoch  (00:00:00J  anuary  1,  1970  UTC). 
at  will  not  schedulejobs  beyond  the  year  2037. 

DEPENDENCIES 

HP  Process  Resource  Manager 

If  the  optional  HP  Process  Resource  Management  (PRM)  software  is  installed  and  configured,  jobs  are 
launched  in  the  initial  process  resource  group  of  the  user  that  scheduled  the  job.  The  user's  initial  group  is 
determined  at  the  time  the  job  is  started,  not  when  the  job  is  scheduled.  If  the  user's  initial  group  is  not 
defined,  the  job  runs  in  the  user  default  group  (PRMID=1).  See  prmconfig(l)  for  a  description  of  how  to 
configure  HP  PRM,  and  prmconf(4)  for  a  description  of  how  the  user's  initial  process  resource  group  is 
determined. 


AUTHOR 

at  was  developed  by  AT&T  and  HP. 


FILES 


/usr/bin/ sh 

/ var / adm/ cron 

/ var/ adm/ cron/ . proto 


/usr/lib/cron/at . allow 
/usr/lib/cron/at . deny 
/var/ adm/ cron/ queuedef s 
/var/ spool/cron/ at  jobs 


POSIX  shell 

Main  cron  directory 

This  file  contains  a  set  of  shell  commands  which  are  added  to  the  at 

job  file  to  make  the  environment  for  the  at  job  same  as  the  current 

environment.  Seeproto(4). 

List  of  allowed  users 

List  of  denied  users 

Scheduling  information 

Spool  area 


SEE  ALSO 

crontab(l),  kill(l),  mail(l),  nice(l),  ps(l),  sh(l),  stty(l),  cron(lM),  proto(4),  queuedefs(4). 

HP  Process  Resource  Manager: 

prmconfig(l),  prmconf(4)  in  HP  Process  Resource  Manager  User'sGuide. 
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STANDARDS  CONFORMANCE 

at:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 

batch:  SVI  D2,  SVI  D3,  XPG2,  XPG3,  XPG4 
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NAME 

attributes  -  describe  an  audio  file 

SYNOPSIS 

/opt/audio/bin/attributes  filename 

DESCRIPTION 

This  command  provides  information  about  an  audio  file,  including  file  format,  data  format,  sampling  rate, 
number  of  channels,  data  length  and  header  length. 

EXAMPLE 

The  foil  owing  is  an  example  of  using  attributes  on  an  audio  file  supplied  with  HP-UX. 

$  /opt/audio/bin/attributes  /opt/audio/sounds/welcome . au 

File  Name:  /opt/audio/sounds/welcome.au 

File  Type :  NeXT/Sun 

Data  Format :  Mu-law 

Sampling  Rate:  22050 

Channels :  Mono 

Duration:    1.972  seconds 

Bits  per  Sample:  8 

Header  Length:    40  bytes 

Data  Length:    434  92  bytes 

AUTHOR 

attributes  was  developed  by  HP. 

Sun  is  a  trademark  of  Sun  Microsystems,  Inc. 
NeXT  is  a  trademark  of  NeXT  Computers,  I  nc. 

SEE  ALSO 

audio(5),  asecureCLM),  aserver(lM),  convert(l),  send  sound(l). 
Using  theAudio  Developer's  Kit 
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NAME 

awk  -  pattern-directed  scanningand  processing  language 
SYNOPSIS 

awk  [-Ffs]  [-v  var=value]  [program  |  -f  progfile  ...]  [file  ...] 
DESCRIPTION 

awk  scans  each  input  file  for  lines  that  match  any  of  a  set  of  patterns  specified  literally  in  program  or  in 
one  or  more  files  specified  as  -f  progfile.  With  each  pattern  there  can  bean  associated  action  that  is  to  be 
performed  when  a  line  in  a  file  matches  the  pattern.  Each  line  is  matched  against  the  pattern  portion  of 
every  pattern-action  statement,  and  the  associated  action  is  performed  for  each  matched  pattern.  The  file 
name  -  means  the  standard  input.  Any  file  of  the  form  var=value  is  treated  as  an  assignment,  not  a 
filename.  An  assignment  is  evaluated  at  the  time  it  would  have  been  opened  if  it  were  a  filename,  unless 
the  -v  option  is  used. 

An  input  line  is  made  up  of  fields  separated  by  white  space,  or  by  regular  expression  FS.  The  fields  are 
denoted  $1,  $2,      $0  refers  to  the  entire  line. 

Options 

awk  recognizes  the  following  options  and  arguments: 

-F  fs  Specify  regular  expression  used  to  separate  fields.  The  default  is  to  recognize  space 

and  tab  characters,  and  to  discard  leading  spaces  and  tabs.  If  the  -F  option  is  used, 
leading  input  field  separators  are  no  longer  discarded. 

-f  progfile  Specify  an  awk  program  file.  Up  to  100  program  files  can  be  specified.  The  pattern- 
action  statements  in  these  files  are  executed  in  the  same  order  as  the  files  were 
specified. 

-v  var=value  Cause  var=value  assignment  to  occur  before  the  BEGIN  action  (if  it  exists)  is  exe- 
cuted. 

Statements 

A  pattern-action  statement  has  the  form: 

pattern  {  action  } 

A  missing  {  action  }  means  print  the  line;  a  missing  pattern  always  matches.  Pattern-action  statements 
are  separated  by  new-lines  or  semicolons. 

An  action  is  a  sequence  of  statements.  A  statement  can  be  one  of  the  following: 

if  ( expression  )  statement  [  else  statement  ] 

while  ( expressi on )  statement 

for  ( expression  ;  expression  ;  expression)  statement 

for(var  in  array)  statement 

do  statement  while  ( expression  ) 

break 
continue 

{ [  statement    . . .  ] } 

expression  #  commonly    var  =  expression 

print  [expression-list]  [  >  expression] 

printf  format  [,  expression-list]  [  >  expression] 

return  [expression] 

next  #  skip  remaining  patterns  on  this  input  line. 

delete  array  [expression]  #  delete  an  array  element. 

exit  [expression]  #  exit  immediately;   status  is  expression. 

Statements  are  terminated  by  semicolons,  newlines  or  right  braces.  An  empty  expression-list  stands  for 
$0.  String  constants  are  quoted  ("  "),  with  the  usual  C  escapes  recognized  within.  Expressions  take  on 
string  or  numeric  values  as  appropriate,  and  are  built  using  the  operators +, -,  *,  /,  %,  "  (exponentiation), 
and  concatenation  (indicated  by  a  blank).  The  operators  ++,  — ,  +=,  -=,  *=,  /=,  %=,  **=,  >,  >=,  <, 
<=,==,  !=,  and  ?:  are  also  available  in  expressions.  Variables  can  be  scalars,  array  elements  (denoted 
x  [i  ] )  or  fields.  Variables  are  initialized  to  the  null  string.  Array  subscripts  can  be  any  string,  not  neces- 
sarily numeric  (this  allows  for  a  form  of  associative  memory).  Multiple  subscripts  such  as  [i,j,k]  are 
permitted.  The  constituents  are  concatenated,  separated  by  the  value  of  SUBSEP. 
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The  print  statement  prints  its  arguments  on  the  standard  output  (or  on  a  file  if  >file  or  »file  is  present 
or  on  a  pipe  if  |  cmd  is  present),  separated  by  the  current  output  field  separator,  and  terminated  by  the  out- 
put record  separator,  file  and  cmd  can  be  literal  names  or  parenthesized  expressions.  Identical  string 
values  in  different  statements  denote  the  same  open  file.  The  printf  statement  formats  its  expression 
I  i  st  accordi  ng  to  the  format  (see  pri  ntf  (3)). 

Built-in  Functions 

The  built-in  function  close  (expr)  closes  the  file  or  pipe  expr  opened  by  a  print  or  printf  state- 
ment or  a  cal I  to  getline  with  the  same  string-valued  expr.  This  function  returns  zero  if  successful,  oth- 
erwise, it  returns  non-zero. 

The  customary  functions  exp,  log,  sqrt,  sin,  cos,  atan2  are  built  in.  Other  built-in  functions  are: 
blength[([s])  ] 

Length  of  its  associated  argument  (in  bytes)  taken  as  a  string,  or  of  $0  if  no  argu- 
ment. 

length  [([s])  ]  Length  of  its  associated  argument  (in  characters)  taken  as  a  string,  or  of  $0  if  no 
argument. 

rand()  Returns  a  random  number  between  zero  and  one. 

srand  ( [expr  ] )  Sets  the  seed  value  for  rand,  and  returns  the  previous  seed  value.  If  no  argument  is 
given,  the  time  of  day  is  used  as  the  seed  value;  otherwise,  expr  is  used. 

int(x)  Truncates  to  an  integer  value 

substr  (s,  m  [,  n] ) 

Return  the  at  most  n-character  substring  of  s  that  begins  at  position  m,  numbering 
from  1.  If  n  is  omitted,  the  substring  is  limited  by  the  length  of  string  s. 

index  (  s,  t )  Return  the  position,  in  characters,  numbering  from  1,  in  string  s  where  string  t  first 
occurs,  or  zero  if  it  does  not  occur  at  all. 

match  (  s,  ere)  Return  the  position,  in  characters,  numbering  from  1,  in  string  s  where  the  extended 
regular  expression  ere  occurs,  or  0  if  it  does  not.  The  variables  RSTART  and 
rlength  are  set  to  the  position  and  length  of  the  matched  string. 

split  (  s,  a[ ,  fs] ) 

Splits  the  string  s  into  array  elements  a  [1] ,  a  [2]        a  [n] ,  and  returns  n.  The 

separation  is  done  with  the  regular  expression  fs,  or  with  the  field  separator  FS  if  fs 
is  not  given. 

sub  (  ere,  repl  [ ,  in] ) 

Substitutes  repl  for  the  first  occurrence  of  the  extended  regular  expression  ere  in  the 
string  in.  If  in  is  not  given,  $0  is  used. 

gsub  Same  as  sub  except  that  all  occurrences  of  the  regular  expression  are  replaced; 

sub  and  gsub  return  the  number  of  replacements. 

sprintf  (  fmt,  expr,    .  .  .  ) 

String  resulting  from  formatting  expr ...  according  to  the  pri  ntf  (3S)  format  fmt 

system  ( cmd )     Executes  cmd  and  returns  its  exit  status 

toupper  ( s)       Converts  the  argument  string  s  to  uppercase  and  returns  the  result. 

tolower  ( s)       Converts  the  argument  string  s  to  lowercase  and  returns  the  result. 

The  built-in  function  getline  sets  $0  to  the  next  input  record  from  the  current  input  file;  getline  < 
filesets  $0  to  the  next  record  from  file,  getline  x  sets  variablex  instead.  Finally,cmd  |  getline 
pipes  the  output  of  cmd  into  getline;  each  call  of  getline  returns  the  next  line  of  output  from  cmd. 
I  n  all  cases,  getline  returns  1  for  a  successful  input,  0  for  end  of  file,  and  -1  for  an  error. 

Patterns 

Patterns  are  arbitrary  Boolean  combinations  (with  !  ||  &&)  of  regular  expressions  and  relational  expres- 
sions, awk  supports  Extended  Regular  Expressions  as  described  in  regexp(5).  Isolated  regular  expres- 
sions in  a  pattern  apply  to  the  entire  line.  Regular  expressions  can  also  occur  in  relational  expressions, 
using  the  operators  "and  !~.  /re/ is  a  constant  regular  expression;  any  string  (constant  or  variable)  can 
be  used  as  a  regular  expression,  except  in  the  position  of  an  isolated  regular  expression  in  a  pattern. 
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A  pattern  can  consist  of  two  patterns  separated  by  a  comma;  in  this  case,  the  action  is  performed  for  all 
lines  from  an  occurrence  of  the  first  pattern  though  an  occurrence  of  the  second. 

A  relational  expression  is  one  of  the  following: 

expression  matchop  regular-expression 
expression  re! op  expression 
expression  in  array-name 
(expr.expr,...)  in  array-name 

where  a  relop  is  any  of  the  six  relational  operators  in  C,  and  a  matchop  is  either  ~  (matches)  or  !  ~  (does 
not  match).  A  conditional  is  an  arithmetic  expression,  a  relational  expression,  or  a  Boolean  combination  of 
the  two. 

Thespecial  patterns  BEGIN  and  END  can  be  used  to  capture  control  before  the  first  input  lineis  read  and 
after  the  last.    BEGIN  and  END  do  not  combine  with  other  patterns. 


Special  Characters 

The  foil  owing  special  escape  sequences  are  recognized  by  awk  in  both  regular  expressions  and  strings: 

Escape  Meaning 

\a  alert  character 

\b  backspace  character 

\f  form-feed  character 

\n  new-line  character 

\r  carriage-return  character 

\t  tab  character 

\v  verti  cal  -tab  character 

\nnn  1- to  3-digit  octal  value nnn 

\xhhh  1- to  n-digit  hexadecimal  number 

Variable  Names 

Variable  names  with  special  meanings  are: 


FS 

NF 
NR 

FNR 

FILENAME 

RS 

OFS 

ORS 

OFMT 

CONVFMT 

SUBSEP 

ARGC 
ARGV 


Input  field  separator  regular  expression;  a  space  character  by  default;  alsosettable 
by  option  -Ffs. 

The  number  of  fields  in  the  current  record. 

The  ordinal  number  of  the  current  record  from  the  start  of  input.  I  nside  a  BEGIN 
action  the  value  is  zero.  I  nside  an  END  action  the  value  is  the  number  of  the  last 
record  processed. 

The  ordinal  number  of  the  current  record  in  the  current  file.  Inside  a  BEGIN 
action  the  value  is  zero.  I  nside  an  END  action  the  value  is  the  number  of  the  last 
record  processed  in  the  last  file  processed. 

A  pathname  of  the  current  input  file. 

The  input  record  separator;  a  newline  character  by  default. 

The  print  statement  output  field  separator;  a  space  character  by  default. 

The  print  statement  output  record  separator;  a  newline  character  by  default. 

Output  format  for  numbers  (default  % .  6g).  If  the  value  of  OFMT  is  not  a 
floating-point  format  specification,  the  results  are  unspecified. 

I  nternal  conversion  format  for  numbers  (default  % .  6g).  If  the  value  of  CONVFMT 
is  not  a  floating-point  format  specification,  the  results  are  unspecified. 

The  subscript  separator  string  for  multi-dimensional  arrays;  the  default  value  is 
"\  034" 

The  number  of  elements  in  the  ARGV  array. 

An  array  of  command  line  arguments,  excluding  options  and  the  program  argu- 
ment numbered  from  zerotoARGC-1. 

The  arguments  in  ARGV  can  be  modified  or  added  to;  ARGC  can  be  altered.  As 
each  input  file  ends,  awk  will  treat  the  next  non-null  element  of  ARGV,  up  to  the 
current  value  of  ARGC-1,  inclusive,  as  the  name  of  the  next  input  file.  Thus,  setting 
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an  element  of  ARGV  to  null  means  that  it  will  not  be  treated  as  an  input  file.  The 
name  -  indicates  the  standard  input.  If  an  argument  matches  the  format  of  an 
assignment  operand,  this  argument  will  be  treated  as  an  assignment  rather  than  a 
file  argument. 

ENVIRON  Array  of  environment  variables;  subscripts  are  names.  For  example,  if  environ- 

ment variable V=thing,  ENVIRON  [  "V"  ]  produces  thing. 

RSTART  The  starting  position  of  the  string  matched  by  the  match  function,  numbering 

from  1.  This  is  always  equivalent  to  the  return  value  of  the  match  function. 

RLENGTH  The  length  of  the  string  matched  by  the  match  function. 

Functions  can  be  defined  (at  the  position  of  a  pattern-action  statement)  as  follows: 

function  foo(a,   b,   c)    {  return  x  } 

Parameters  are  passed  by  value  if  scalar,  and  by  reference  if  array  name.  Functions  can  be  called  recur- 
sively. Parameters  are  local  to  the  function;  all  other  variables  are  global. 

Note  that  if  pattern-action  statements  are  used  in  an  HP-UX  command  line  as  an  argument  to  the  awk 
command,  the  pattern-action  statement  must  be  enclosed  in  single  quotes  to  protect  it  from  the  shell.  For 
example,  to  print  lines  longer  than  72  characters,  the  pattern-action  statement  as  used  in  a  script  (-f 
progfile command  form)  is: 

length  >  72 

The  same  pattern  action  statement  used  as  an  argument  to  the  awk  command  is  quoted  in  this  manner: 
awk  'length  >  72' 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  Provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If 

LANG  is  unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  interna- 
tionalization variables  contains  an  invalid  setting,  awk  will  behave  as  if  all  internationali- 
zation variables  are  set  to  "C".  See  environ  (5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization 
variables. 

LC_CTYPE  Determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the 
classification  of  characters  as  printable,  and  the  characters  matched  by  character  class 
expressions  in  regular  expressions. 

LC_NUMERIC  Determines  the  radix  character  used  when  interpreting  numeric  input,  performing  conver- 
sion between  numeric  and  string  values  and  formatting  numeric  output.  Regardless  of 
locale,  the  period  character  (the  decimal-point  character  of  the  POSIX  locale)  is  the 
decimal-point  character  recognized  in  processing  awk  programs  (including  assignments  in 
command-line  arguments). 

LC_COLLATE  Determines  the  locale  for  the  behavior  of  ranges,  equivalence  classes  and  multi-character 
collating  elements  within  regular  expressions. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH       Determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

PATH  Determines  the  search  path  when  looking  for  commands  executed  by  system (cmd)  ,  or 

input  and  output  pipes. 

In  addition,  all  environment  variables  will  bevisiblevia  the  awk  variable  ENVIRON. 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported  except  that  variable  names  must  contain  only 
ASCI  I  characters  and  regular  expressions  must  contain  only  valid  characters. 
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DIAGNOSTICS 

awk  supports  up  to  199  fields  ($1,  $2       $199)  per  record. 

EXAMPLES 

Print  lines  longer  than  72  characters: 

length  >  72 

Print  first  two  fields  in  opposite  order: 

{  print  $2,    $1  } 
Same,  with  input  fields  separated  by  comma  and/or  blanks  and  tabs: 

BEGIN    {   FS  =   ",[    \t]*|[    \t]+"  } 
{  print   $2,    $1  } 

Add  up  first  column,  print  sum  and  average: 

{  s  +=  $1  }" 

END  {  print   "sum  is",    s,    "  average  is",    s/NR  } 

Print  all  lines  between  start/stop  pairs: 

/start/,  /stop/ 

Simulate  echo  command  (see echo(l)): 

BEGIN       {  #  Simulate  echo(l) 

for    (i  =  1;    i  <  ARGC;    i++)    printf   "%s   ",   ARGV [ i ] 
printf  "\n" 
exit  } 

AUTHOR 

awk  was  developed  by  AT&T,  IBM,  OSF,  and  HP. 

SEE  ALSO 

lex(l),  sed(l). 

A.  V.  Aho,  B.  W.  Kernighan,  P.  J  .  Weinberger:  TheAWK  Programming  Language,  Addi son-Wesley,  1988. 

STANDARDS  CONFORMANCE 

awk:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 


Section  1-38 


-5- 


HP-UX  Release  Hi:  December  2000 


banner  (1) 


banner  (1) 


NAME 

banner  -  make  posters  in  large  letters 

SYNOPSIS 

banner  strings 

DESCRIPTION 

banner  prints  its  arguments  (each  up  to  10  characters  long)  in  large  letters  on  the  standard  output. 

Each  argument  is  printed  on  a  separate  line.  Note  that  multiple-word  arguments  must  be  enclosed  in 
quotes  in  order  to  be  printed  on  the  same  line. 

EXAMPLES 

Print  the  message  "Good  luck  Susan"  in  large  letters  on  the  screen: 

banner  "Good  luck"  Susan 
Thewords  Good  luck  are  displayed  on  one  line,  and  Susan  is  displayed  on  a  second  line. 

WARNINGS 

This  command  is  likely  to  be  withdrawn  from  X/Open  standards.  Applications  using  this  command  might 
not  be  portable  to  other  vendors'  platforms. 

SEE  ALSO 

echo(l). 

STANDARDS  CONFORMANCE 

banner:  SVID2,  SVID3,  XPG2,  XPG3 
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NAME 

basename,  dirname-  extract  portions  of  path  names 

SYNOPSIS 

basename  string  [suffix] 

dirname  [string] 
DESCRIPTION 

basename  deletes  any  prefix  ending  in  /  and  the  suffix  (if  present  in  string)  from  string,  and  prints  the 
result  on  the  standard  output.  If  string  consists  entirely  of  slash  characters,  string  is  set  to  a  single  slash 
character.  If  there  are  any  trailing  slash  characters  in  string,  they  are  removed.  If  the  suffix  operand  is 
present  but  not  identical  to  the  characters  remaining  in  string,  but  it  is  identical  to  a  suffix  of  the  charac- 
ters remaining  in  string,  the  suffix  is  removed  from  string,  basename  is  normally  used  inside  command 
substitution  marks  (       )  within  shell  procedures. 

dirname  delivers  all  but  the  last  level  of  the  path  name  in  string.  If  string  does  not  contain  a  directory 
component,  dirname  returns  .,  indicating  the  current  working  directory. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  string  and,  in  the  case  of  basename,  suffix  as  single  and/or 
multi-byte  characters. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used 
as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  basename  and  dirname  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 


The  following  shell  script,  invoked  with  the  argument  /usr/src/cmd/cat .  c,  compiles  the  named  file 
and  moves  the  output  to  a  file  named  cat  in  the  current  directory: 

cc  $1 

mv  a. out    'basename  $1  .c' 
The  foil  owing  example  sets  the  shell  variable  NAME  to  /usr/src/cmd: 
NAME= * dirname   /usr/src/cmd/cat . c x 

RETURNS 

basename  and  dirname  return  one  of  the  foil  owing  values: 


SEE  ALSO 

expr(l),  sh(l). 

STANDARDS  CONFORMANCE 

basename:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 

dirname:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 


EXAMPLES 


0 


1 


Successful  completion. 

I  ncorrect  number  of  command-line  arguments. 
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NAME 

be  -  arbitrary-precision  arithmetic  language 

SYNOPSIS 

be  [-c]  [-1]  [file  ...] 

DESCRIPTION 

be  is  an  interactive  processor  for  a  language  that  resembles  C  but  provides  unlimited-precision  arithmetic. 
It  takes  input  from  any  files  given,  then  reads  the  standard  input. 

Options: 

be  recognizes  the  following  command-line  options: 

-c  Compileonly.    be  is  actually  a  preprocessor  for  dc  which  be  invokes  automatically  (see 

dc(lj).  Specifyi  ng  -c  prevents  i  nvoki  ng  dc,  and  sends  the  dc  i  nput  to  standard  output. 

-1  causes  an  arbitrary-precision  math  library  to  be  predefined.  As  a  side  effect,  the  scale  fac- 

tor is  set. 

Program  Syntax: 

L     a  single  letter  in  the  range  a  through  z; 

E  expression; 

S  statement; 

R     relational  expression. 

Comments: 

Comments  are  enclosed  in  /*  and  */. 

Names: 

Names  include: 

simple  variables:  L 

array  elements:  L  [  E  ] 

Thewords  ibase.obase,  and  scale 

stacks:  L 

Other  Operands 

Other  operands  include: 

Arbitrarily  long  numbers  with  optional  sign  and  decimal  point. 
(E  ) 

sqrt  (  E  ) 

length  (  E  )  number  of  significant  decimal  digits 

scale  (E  )  number  of  digits  right  of  decimal  point 

L  (E  E  ) 

Strings  of  ASCII  characters  enclosed  in  quotes  ("). 

Arithmetic  Operators: 

Arithmetic  operators  yield  an  E  as  a  result  and  include: 

+    -*/%"  (%  is  remainder  (not  mod,  see  below);  "is  power). 

++    --  (prefix  and  append;  apply  to  names) 

=    +=    -=    *=    /=    %=  "= 

Relational  Operators 

Relational  operators  yield  an  R  when  used  as  E  op  E: 

==<=>=     !=     <  > 
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Statements 

E 

{S;...;S} 
if  (  R  )  S 
while (  R  )  S 
for  (  E  ;  R  ;  E  )  S 
null  statement 
break 
quit 

Function  Definitions: 

define  L  (  L       L  )  { 

autoL  L 

S;  ...  S 
return  (  E  ) 

} 

Functions  in  -I  Math  Library: 

Functions  in  the  -1  math  library  include: 


s(x)  si  ne 

c(x)  cosine 

e(x)  exponential 

l(x)  log 

a(x)  arctangent 

j(n,x)  Bessel  function 


All  function  arguments  are  passed  by  value.  Trigonometric  angles  are  in  radians  where  2  pi  radians  =  360 
degrees. 

The  value  of  a  statement  that  is  an  expression  is  printed  unless  the  main  operator  is  an  assignment.  No 
operators  are  defined  for  strings,  but  the  string  is  printed  if  it  appears  in  a  context  where  an  expression 
result  would  be  printed.  Either  semicolons  or  new-lines  can  separate  statements.  Assignment  to  scale 
influences  the  number  of  digits  to  be  retained  on  arithmetic  operations  in  the  manner  of  dc(l).  Assign- 
ments to  ibase  or  obase  set  the  input  and  output  number  radix  respectively,  again  as  defined  by  dc(l). 

The  same  letter  can  be  used  simultaneously  as  an  array,  a  function,  and  a  simple  variable.  All  variables 
are  global  to  the  program.  "Auto"  variables  are  pushed  down  during  function  calls.  When  using  arrays  as 
function  arguments  or  defining  them  as  automatic  variables,  empty  square  brackets  must  follow  the  array 
name. 

The  %  operator  yields  the  remainder  at  the  current  scale,  not  the  integer  modulus.  Thus,  at  scale  1,  7  % 
3  is  .1  (one  tenth),  not  1.  This  is  because  (at  scale  1)  7  /  3  is  2.3  with  .1  as  the  remainder. 

EXAMPLES 

Define  a  function  to  compute  an  approximate  value  of  the  exponential  function: 

scale  =  20 
define  e  (x)  { 

auto  a,  b,   c,   i,  s 

a  =  1 

b  =  1 

s  =  1 

for(i=l;    1==1;    i++) { 
a  =  a*x 
b  =  b*i 
c  =  a/b 

if(c  ==  0)    return (s) 
s  =  s+c 

} 

} 

Print  approximate  values  of  the  exponential  function  of  the  first  ten  integers. 
for(i=l;    i<=10;    i++)  e(i) 
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WARNINGS 

There  are  currently  no  &&  (and)  or  |  |  (OR)  comparisons. 
The  for  statement  must  have  all  three  expressions, 
quit  i s  i  nterpreted  when  read,  not  when  executed. 

bc's  parser  is  not  robust  in  the  face  of  input  errors.  Some  simple  expression  such  as  2+2  helps  get  it  back 
into  phase. 

The  assignment  operators:  =+  =-  =*  =/  =%  and  ="  are  obsolete.  Any  occurences  of  these 
operators  cause  a  syntax  error  with  the  exception  of  =-  which  is  interpreted  as  =  followed  by  a  unary 
minus. 

Neither  entire  arrays  nor  functions  can  be  passed  as  function  parameters. 


SEE  ALSO 

bs(l),  dc(l). 

be  tutorial  in  Number  Processing  Users  Guide 

STANDARDS  CONFORMANCE 

be:  XPG4,  POSIX.2 


FILES 


/usr/bin/dc 
/usr/lib/lib.b 


desk  calculator  executable  program 
mathematical  library 
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NAME 

bdiff  -  diff  for  large  files 

SYNOPSIS 

bdiff  filel  file2  [n]  [-s] 

DESCRIPTION 

bdiff  compares  two  files  and  produces  output  identical  to  what  would  be  produced  by  diff  (see  diff(l)), 
specifying  changes  that  must  be  made  to  make  the  files  identical,  bdiff  is  designed  for  handling  files 
that  are  too  large  for  diff,  but  it  can  be  used  on  files  of  any  length. 

bdiff  processes  files  as  follows: 

•  Ignore  lines  common  to  the  beginning  of  both  files. 

•  Split  the  remainder  of  each  file  into  n-line  segments,  then  execute  diff  on  corresponding  seg- 
ments. The  default  value  of  n  is  3500. 

Command-Line  Arguments 

bdiff  recognizes  the  following  command-line  arguments: 

filel 

file2  Names  of  two  files  to  be  compared  by  bdiff.  If  filel  or  file2  (but  not  both)  is  -,  stan- 

dard input  is  used  instead. 

n  If  a  numeric  value  is  present  as  the  third  argument,  the  files  are  divided  into  n-line  seg- 

ments before  processing  by  diff.  Default  value  for  n  is  3500.  This  option  is  useful 
when  3500-linesegments  are  too  large  for  processing  by  diff . 

-s  Silent  option  suppresses  diagnostic  printing  by  bdiff,  but  does  not  suppress  possible 

error  messages  from  diff).  If  the  n  and  -s  arguments  are  both  used,  the  n  argument 
must  precede  the  -s  option  on  the  command  line  or  it  will  not  be  properly  recognized. 

EXTERNAL  INFLUENCES 
Envi  ronment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  bdiff  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

both  files  standard  input  (bd2) 

Standard  input  was  specified  for  both  files.  Only  one  file  can  be  specified  as  standard  input. 

non-numeric  limit  (bd4) 

A  non-numeric  value  was  specified  for  the  n  (third)  argument. 

EXAMPLES 

Find  differences  between  two  large  files:  filel  and  file2,  and  place  the  result  in  a  new  file  named 
diffs_1.2. 

bdiff  filel  file2  >diffs_1.2 

Do  the  same,  but  limit  file  length  to  1400  lines;  suppress  error  messages: 

bdiff  filel  file2  1400  -s  >diffs_1.2 

WARNINGS 

bdiff  produces  output  identical  to  output  from  diff,  and  makes  the  necessary  line-number  corrections 
so  that  the  output  looks  like  it  was  processed  by  diff.  However,  depending  on  where  the  files  are  split, 
bdiff  may  or  may  not  find  a  fully  minimized  set  of  file  differences. 


Section  1-44 


-1- 


HP-UX  Release  Hi:  December  2000 


bdiff(l) 


FILES 

/tmp/bd?????? 

SEE  ALSO 

diff(l). 


bdiff(l) 
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NAME 

bfs-  big  file  scanner 

SYNOPSIS 

bfs  [-]  name 

DESCRIPTION 

bfs  is  similar  to  ed  except  that  it  is  read-only  (see  ed(l))  bfs  can  handlefiles  with  up  to  32K  -  1  lines; 
each  line  can  contain  up  to  512  characters,  including  the  new-line  character,  bfs  is  usually  more  efficient 
than  ed  for  scanning  a  file,  since  the  file  is  not  copied  to  a  buffer.  Historically,  this  command  was  most 
useful  for  identifying  sections  of  a  large  file  where  csplit  could  be  used  to  divide  it  into  more  manage- 
able pieces  for  editing  (see  csplit(l)).  However,  most  editors  now  support  files  larger  than  the  above- 
mentioned  limits. 

Normally,  the  size  of  the  file  being  scanned  is  printed,  as  is  the  size  of  any  file  written  with  the  w  com- 
mand. The  optional  -  suppresses  printing  of  sizes.  I  nput  is  prompted  with  *  if  P  and  a  carriage-return 
are  typed,  as  in  ed.  Prompting  can  be  turned  off  again  by  inputting  another  P  and  pressing  Return.  Note 
that  messages  are  given  in  response  to  errors  if  prompting  isturned  on. 

bfs  supports  the  Basic  Regular  Expression  (RE)  syntax  (see  regexp(5))  with  the  addition  that  a  null  re 
(e.g.,  //)  is  equivalent  to  the  last  re  encountered.  All  address  expressions  described  under  ed  are  sup- 
ported. In  addition,  regular  expressions  can  be  surrounded  with  two  symbols  besides  /  and  ?:  >  indi- 
cates downward  search  without  wrap-around,  and  <  indicates  upward  search  without  wrap-around.  There 
is  a  slight  difference  in  mark  names:  only  the  letters  a  through  z  can  be  used,  and  all  26  marks  are 
remembered. 

The  e,  g,  v,  k,  n,  p,  q,  w,  =,  !  and  null  commands  operate  as  described  under  ed.  Commands  such  as  - 
— ,  +++-,  +++=,  -12,  and  +4p  are  accepted.  Note  that  l,10p  and  1,10  both  print  the  first  ten 
lines.  The  f  command  only  prints  the  name  of  the  file  being  scanned;  there  is  no  remembered  file  name. 
The  w  command  is  independent  of  output  diversion,  truncation,  or  crunching  (see  the  xo,  xt,  and  xc 
commands,  below).  Thefollowing  additional  commands  are  available: 

xf  file  Further  commands  are  taken  from  the  named  file.  When  an  end-of-file  is  reached,  an  inter- 

rupt signal  is  received  or  an  error  occurs,  reading  resumes  with  the  file  containing  the  xf . 
Xf  commands  may  be  nested  to  a  depth  of  10. 

xo  [file]  Further  output  from  the  p  and  null  commands  is  diverted  to  the  named  file,  which,  if 
necessary,  is  created  mode  666.  If  file  is  missing,  output  is  diverted  to  the  standard  output. 
Note  that  each  diversion  causes  truncation  or  creation  of  the  file. 

:  label  This  positions  a  label  in  a  command  file,  label  is  terminated  by  a  new-line,  and  blanks 

between  the  :  and  the  start  of  label  are  ignored.  This  command  can  also  be  used  to  insert 
comments  intoa  command  file,  since  labels  need  not  be  referenced. 

(. ,  .  )xb/regular  expression /label 

A  jump  (either  upward  or  downward)  is  made  to  label  if  the  command  succeeds.  It  fails 
under  any  of  thefollowing  conditions: 

1.  Either  address  is  not  between  1  and  $. 

2.  The  second  address  is  less  than  the  first. 

3.  The  regular  expression  does  not  match  at  least  one  line  in  the  specified  range, 
including  the  first  and  last  lines. 

On  success,  .  is  set  to  the  line  matched  and  a  jump  is  made  to  label .  This  command  is  the 
only  one  that  does  not  issue  an  error  message  on  bad  addresses.  Thus  it  can  be  used  to  test 
whether  addresses  are  bad  before  other  commands  are  executed.  Note  that  the  command 

xb/ label 

is  an  unconditional  jump. 

The  xb  command  isallowed  only  if  it  is  read  from  someplace  other  than  a  terminal.  If  it  is 
read  from  a  pipe  only  a  downward  jump  is  possible. 

List  the  marks  currently  in  use  (marks  are  set  by  the  k  command). 

Output  from  the  p  and  null  commands  is  truncated  to  at  most  number  characters.  The  ini- 
tial number  is  255. 


xn 

xt  number 
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xv[digit]  [spaces]  [val  ue] 

The  variable  name  is  the  specified  digit  following  the  xv.  xv5100  or  xv5  100  both 
assign  the  value  100  to  the  variable  5.  Xv61, 10  Op  assigns  the  value  l,100ptothe 
variable  6.  To  reference  a  variable,  put  a  %  in  front  of  the  variable  name.  For  example, 
usingthe  above  assignments  for  variables  5  and  6: 

l,%5p 

1,%5 

%6 

all  print  the  first  100  lines. 
g/%5/p 

globally  searches  for  the  characters  100  and  prints  each  line  containing  a  match.  To 
escape  the  special  meaning  of  %,  a  \  must  precede  it.  For  example,  to  match  and  list  lines 
in  a  program  file  that  contain  printf  ()  format  strings  specifying  characters,  decimal 
integers,  or  strings,  the  foil  owing  could  be  used: 

g/".*\%[cds]/p 

Another  feature  of  the  xv  command  is  that  the  first  line  of  output  from  an  hp-ux  com- 
mand can  be  stored  into  a  variable.  The  only  requirement  is  that  the  first  character  of 
value  be  an  !.  For  example: 

.w  junk 
xv5 ! cat  junk 
!  rm  junk 
!echo  "%5" 
xv6!expr  %6  +  1 

each  put  the  current  line  into  variable  5,  print  it,  and  increment  the  variable  6  by  one.  To 
escape  the  special  meaning  of  !  as  the  first  character  of  value,  precede  it  with  a  \. 

xv7\!date 

stores  the  val  ue  !date  into  variable  7. 

xbz  label 

xbn  label  These  two  commands  test  the  last  saved  return  codefrom  the  execution  of  an  hp-ux  system 
command  ( !  command )  for  a  zero  or  non-zero  val  ue,  respectively,  and  cause  a  branch  to  the 
specified  label.  The  two  examples  below  both  search  for  the  next  five  lines  containing  the 
string  size. 

First  example: 

xv55 
:  1 

/ size/ 

xv5!expr  %5  -  1 

!if   [  %5   !=  0  ]    ;   then  exit  2  ;  fi 
xbn  1 

Second  Example: 

xv45 
:  1 

/ size/ 

xv4!expr  %4  -  1 

!if   [  %4  =  0  ]    ;   then  exit  2  ;  fi 
xbz  1 

xc  [switch]     If  switch  is  1,  output  from  the  p  and  null  commands  is  crunched;  if  switch  is  0  it  isn't. 

Without  an  argument,  xc  reverses  switch.  Initially  switch  is  set  for  no  crunching. 
Crunched  output  has  strings  of  tabs  and  blanks  reduced  to  one  blank,  and  blank  lines 
suppressed. 

EXTERNAL  INFLUENCES 
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Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  regular  expressions. 

LC_CTYPE  determines  the  classification  of  characters  as  letters,  and  the  characters  matched  by  character 
class  expressions  in  regular  expressions. 

If  LC_COLLATE  or  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  bfs  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

I  nternational  Code  Set  Support 

Single-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

?  for  errors  in  commands,  if  prompting  is  turned  off.  Self-explanatory  error  messages  when  prompting  is 
on. 

SEE  ALSO 

csplit(l),  ed(l),  lang(5),  regexp(5). 


Section  1-48 


-3- 


HP-UX  Release  Hi:  December  2000 


bs(l) 


bs(l) 


NAME 

bs  -  a  compiler/interpreter  for  modest-sized  programs 

SYNOPSIS 

bs  [file  [args]] 

DESCRIPTION 

bs  is  a  remote  descendant  of  basic  and  SNOBOL4  with  some  C  language  added,  bs  is  designed  for  pro- 
gramming tasks  where  program  development  time  is  as  important  as  the  resulting  speed  of  execution.  For- 
malities of  data  declaration  and  file/process  manipulation  are  minimized.  Line-at-a-time  debugging,  the 
trace  and  dump  statements,  and  useful  run-time  error  messages  all  simplify  program  testing.  Further- 
more, incomplete  programs  can  be  debugged;  inner  functions  can  be  tested  before  outer  functions  have  been 
written,  and  vice  versa. 

If  file  is  specified  on  the  command-line,  it  is  used  for  input  before  any  input  is  taken  from  the  keyboard.  By 
default,  statements  read  from  file  are  compiled  for  later  execution.  Likewise,  statements  entered  from  the 
keyboard  are  normally  executed  immediately  (see  compile  and  execute  below).  Unless  the  final 
operation  is  assignment,  the  result  of  an  immediate  expression  statement  isprinted. 

bs  programs  are  made  up  of  input  lines.  If  the  last  character  on  a  line  is  a  \,  the  line  is  continued,  bs 
accepts  I  i  nes  of  the  fol  I  owi  ng  form: 

statement 
label  statement 

A  label  is  a  name  (see  below)  followed  by  a  colon.  A  label  and  a  variable  can  have  the  same  name. 

A  bs  statement  is  either  an  expression  or  a  keyword  followed  by  zero  or  more  expressions.  Some  key- 
words (clear,  compile,  !,  execute,  include,  ibase,  obase,  and  run)  are  always  executed  as 
they  are  compiled. 

Statement  Syntax: 

expression  The  expression  is  executed  for  its  side  effects  (value,  assignment,  or  function  call).  The 
details  of  expressions  fol  low  the  description  of  statement  types  below. 

break  break  exits  from  the  innermost  for/while  loop. 

clear  Clears  the  symbol  tableand  compiled  statements,    clear  isexecuted  immediately. 

compile  [expression] 

Succeeding  statements  are  compiled  (overrides  the  immediate  execution  default).  The 
optional  expression  is  evaluated  and  used  as  a  file  name  for  further  input.  A  clear  is 
associated  with  this  latter  case,    compile  is  executed  immediately. 

continue      continue  transfers  to  the  loop-continuation  of  the  current  for/while  loop. 

dump  [name]  The  name  and  current  value  of  every  non-local  variable  is  printed.  Optionally,  only  the 
named  variable  is  reported.  After  an  error  or  interrupt,  the  number  of  the  last  statement 
is  displayed.  The  user-function  trace  is  displayed  after  an  error  or  stop  that  occurred  in 
a  function. 

edit  A  call  is  made  to  the  editor  selected  by  the  EDITOR  environment  variable  if  it  is  present, 

or  ed(l)  if  EDITOR  is  undefined  or  null.  If  the  file  argument  is  present  on  the  command 
line,  file  is  passed  to  the  editor  as  the  file  to  edit  (otherwise  no  file  name  is  used).  Upon 
exiting  the  editor,  a  compile  statement  (and  associated  clear)  is  executed  giving  that 
file  name  as  its  argument. 

exit  [expression] 

Return  to  system  level.  Theexpression  isreturned  as  process  status. 

execute       Change  to  immediate  execution  mode  (an  interrupt  has  a  similar  effect).  This  statement 


HP-UX  Release  Hi:  December  2000 


-1- 


Section  1-49 


bs(l) 


bs(l) 


does  not  cause  stored  statements  to  execute  (see  run  below). 

for  name=  expression  expression  statement 
for  name=  expression  expression 

next 

for  expression  ,  expression  ,  expression  statement 
for  expression  ,  expression  ,  expression 

next  The  for  statement  repetitively  executes  a  statement  (first  form)  or  a  group  of  statements 

(second  form)  under  control  of  a  named  variable.  The  variable  takes  on  the  value  of  the 
first  expression,  then  is  incremented  by  one  on  each  loop,  not  to  exceed  the  value  of  the 
second  expression.  The  third  and  fourth  forms  require  three  expressions  separated  by  com- 
mas. The  first  of  these  is  the  initialization,  the  second  is  the  test  (true  to  continue),  and  the 
third  is  the  loop-continuation  action  (normally  an  increment). 

fun  f([a,  ...])  [v,  ...] 

nuf  fun  defines  the  function  name,  arguments,  and  local  variables  for  a  user-written  function. 

Up  to  ten  arguments  and  local  variables  are  allowed.  Such  names  cannot  be  arrays,  nor 
can  they  be  I/O  associated.  Function  definitions  cannot  be  nested.  Calling  an  undefined 
function  is  permissible;  see  function  calls  below. 

freturn       A  way  to  signal  the  failure  of  a  user-written  function.  See  the  interrogation  operator  (?) 

below.  If  interrogation  is  not  present,  freturn  merely  returns  zero.  When  interrogation 
isactive,  freturn  transfers  to  that  expression  (possibly  by-passing  intermediate  function 
returns). 

goto  name    Control  is  passed  to  the  internally  stored  statement  with  the  matching  label. 

ibase  n  ibase  sets  the  input  base  (radix)  to  n.  The  only  supported  values  for  n  are  the  constants 
8,  10  (the  default),  and  16.  Hexadecimal  values  10-15  are  entered  as  a-f.  A  leading  digit 
is  required  (i.e.,  fOa  must  be  entered  as  OfOa).  ibase  (and  obase  discussed  below) 
are  executed  immediately. 

if  expression  statement 
if  expression 

[else...] 

f  i  The  statement  (first  form)  or  group  of  statements  (second  form)  is  executed  if  the  expres- 

sion evaluates  to  non-zero.  The  strings  0  and  ""  (null)  evaluate  as  zero.  In  the  second 
form,  an  optional  else  provides  for  a  second  group  of  statements  to  be  executed  when  the 
first  group  is  not.  The  only  statement  permitted  on  the  same  line  with  an  else  is  an  if; 
only  other  fis  can  be  on  the  same  line  with  a  fi.  The  concatenation  of  else  and  if 
into  an  elif  is  supported.  Only  a  single  fi  is  required  to  close  an  if  ...  elif  ... 
[  else  ...  ]  sequence. 

include  expression 

expression  must  evaluate  to  a  file  name.  The  file  must  contain  bs  source  statements. 
Such  statements  become  part  of  the  program  being  compiled,  include  statements  can- 
not be  nested. 

obase  n        obase  sets  the  output  base  to  n  (see  ibase  above), 
onintr  label 

onintr  onintr  provides  program  control  of  interrupts.  In  the  first  form,  control  passes  to  the 
label  given,  just  as  if  a  goto  had  been  executed  at  the  time  onintr  was  executed.  The 
effect  of  the  statement  is  cleared  after  each  interrupt.  In  the  second  form,  an  interrupt 
causes  bs  to  terminate. 

return  [expression] 

The  expression  is  evaluated  and  the  result  is  passed  back  as  the  value  of  a  function  call.  If 
no  expression  is  given,  zero  is  returned. 

run  The  random  number  generator  is  reset.  Control  is  passed  to  the  first  internal  statement. 

If  the  run  statement  is  contained  in  a  file,  it  should  be  the  last  statement. 


Section  1-50 


-2- 


HP-UX  Release  Hi:  December  2000 


bs(l) 


bs(l) 


stop  Execution  of  internal  statements  is  stopped,    bs  reverts  to  immediate  mode, 

trace  [expression] 

The  trace  statement  controls  function  tracing.  If  the  expression  is  null  (or  evaluates  to 
zero),  tracing  is  turned  off.  Otherwise,  a  record  of  user-function  calls/returns  is  printed. 
Each  return  decrements  the  trace  expression  value. 

while  expression  statement 
while  expression 

next  while  is  similar  to  for  except  that  only  the  conditional  expression  for  loop-continuation 

is  given. 

!  shell  command 

An  immediate  escape  to  the  shell. 

#  ...  This  statement  is  ignored  (treated  as  a  comment). 

Expression  Syntax: 

name  A  name  is  used  to  specify  a  variable.  Names  are  composed  of  a  letter  (uppercase  or  lower- 

case) optionally  followed  by  letters  and  digits.  Only  the  first  six  characters  of  a  name  are 
significant.  Except  for  names  declared  in  fun  statements,  all  names  are  global  to  the  pro- 
gram. Names  can  take  on  numeric  (doublefloat)  values,  string  values,  or  can  be  associated 
with  input/output  (see  the  built-in  function  open()  below). 

name(  [expression  [ ,  expression] ...  ] ) 

Functions  can  be  called  by  a  name  followed  by  the  arguments  in  parentheses  separated  by 
commas.  Except  for  built-in  functions  (listed  below),  the  name  must  be  defined  with  a  fun 
statement.  Arguments  to  functions  are  passed  by  value.  If  the  function  is  undefined,  the 
call  history  to  the  call  of  that  function  is  printed,  and  a  request  for  a  return  value  (as  an 
expression)  is  made.  The  result  of  that  expression  is  taken  to  be  the  result  of  the  undefined 
function.  This  permits  debugging  programs  where  not  all  the  functions  are  yet  defined. 
The  value  is  read  from  the  current  input  file. 

name[  expression  [ ,  expression  ] ...  ] 

This  syntax  is  used  to  reference  either  arrays  or  tables  (see  built-in  table  functions  below). 
For  arrays,  each  expression  is  truncated  to  an  integer  and  used  as  a  specifier  for  the  name. 
The  resulting  array  reference  is  syntactically  identical  to  a  name;  a  [1, 2]  is  the  same  as 
a[l]  [2].  Thetruncated  expressions  are  restricted  to  values  between  0  and  32767. 

number  A  number  is  used  to  represent  a  constant  value.  A  number  is  written  in  Fortran  style,  and 

contains  digits,  an  optional  decimal  point,  and  possibly  a  scalefactor  consisting  of  an  e  fol- 
lowed by  a  possibly  signed  exponent. 

string  Character  strings  are  delimited  by  "  characters.  The  \  escape  character  allows  the  double 

quote  (\"),  new-line  (\n),  carriage  return  (\r),  backspace  (\  b),  and  tab  (\t)  characters  to 
appear  in  a  string.  Otherwise,  \  stands  for  itself. 

(  expression  )    Parentheses  are  used  to  alter  the  normal  order  of  evaluation. 

(  expression  ,  expression  [ ,  expression  ...  ] )  [  expression  ] 

The  bracketed  expression  is  used  as  a  subscript  to  select  a  comma-separated  expression 
from  the  parenthesized  list.  List  elements  are  numbered  from  the  left,  starting  at  zero. 

The  expression: 

(  False,   True  ) [  a  ==  b  ] 

has  the  value  True  if  the  comparison  is  true. 

?  expression  The  interrogation  operator  tests  for  the  success  of  the  expression  rather  than  its  value.  At 
the  moment,  it  is  useful  for  testing  end-of-file  (see  examples  in  the  Programming  Tips  sec- 
tion below),  the  result  of  the  eval  built-in  function,  and  for  checking  the  return  from 
user-written  functions  (see  f  return).  An  interrogation  "trap"  (end-of-file,  etc.)  causes  an 
immediate  transfer  to  the  most  recent  interrogation,  possibly  skipping  assignment  state- 
ments or  intervening  function  levels. 

-  expression    The  result  is  the  negation  of  the  expression. 
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++  name        I  ncrements  the  valueof  the  variable(or  array  reference).  The  result  is  the  new  value. 

—  name       Decrements  the  value  of  the  variable.  The  result  is  the  new  value. 

!  expression     The  logical  negation  of  the  expression.  Watch  out  for  the  shell  escape  command. 

expression  operator  expression  Common  functions  of  two  arguments  are  abbreviated  by  the  two  argu- 
ments separated  by  an  operator  denoting  the  function.  Except  for  the  assignment,  concate- 
nation, and  relational  operators,  both  operands  are  converted  to  numeric  form  before  the 
function  is  applied. 

Binary  Operators  (in  increasing  precedence): 
=  =  is  the  assignment  operator.  The  left  operand  must  be  a  name  or  an  array  element.  The 

result  is  the  right  operand.  Assignment  binds  right  to  left,  all  other  operators  bind  left  to 
right. 

_  _  (underscore)  is  the  concatenation  operator. 

&   |  &  (logical  and)  has  result  zero  if  either  of  its  arguments  are  zero.  It  has  result  one  if  both 

of  its  arguments  are  non-zero;  |  (logical  OR)  has  result  zero  if  both  of  its  arguments  are 
zero.  It  has  result  one  if  either  of  its  arguments  is  non-zero.  Both  operators  treat  a  null 
stri  ng  as  a  zero. 

<<=>>===  != 

The  relational  operators  (<:  less  than,  <=:  less  than  or  equal,  >:  greater  than,  >=: 
greater  than  or  equal,  ==:  equal  to,  !=:  not  equal  to)  return  one  if  their  arguments  are  in 
the  specified  relation,  or  return  zero  otherwise.  Relational  operators  at  the  same  level 
extend  as  follows:  a>b>c  is  equivalent  to  a>b  &  bsc.  A  string  comparison  is  made  if 
both  operands  are  strings. 

+  -  Add  and  subtract. 

*  /  %  Multiply,  divide,  and  remainder. 

Exponentiation. 

Built-in  Functions: 
Dealing  with  arguments 

arg(i)  is  the  value  of  the  i -th  actual  parameter  on  the  current  level  of  function  call.  At  level  zero, 

arg  returns  the  i-th  command-lineargument  (arg(O)  returns bs). 

narg(  )  returns  the  number  of  arguments  passed.  At  level  zero,  the  command  argument  count  is 
returned. 

Mathematical 

abs(x)  i  s  the  absolute  value  of  x. 

atan(x)  is  the  arctangent  of  x.  Its  value  is  between  -ji/2  and  n/2. 

ceil  (x)  returns  the  smallest  integer  not  less  than  x. 

cos(x)  is  the  cosine  of  x  (radians). 

exp(x)  is  the  exponential  function  of  x. 

f  loor  (x)  returns  the  largest  integer  not  greater  than  x. 

log(x)  isthe  natural  logarithm  of  x. 

rand  ( )  is  a  uniformly  distributed  random  number  between  zero  and  one. 

sin(x)  isthesineofx  (radians). 

sqrt(x)  is  the  square  root  of  x. 

String  operations 

size  (s)        the  size  (length  in  bytes)  of  s  is  returned, 
format  (f,  a) 

returns  the  formatted  value  of  a.  f  is  assumed  to  be  a  format  specification  in  the  style  of 
printf(3S).  Only  the  %  ...  f,  %  ...  e,  and  %  .  .  .  s  types  are  safe.  Since  it  is  not  always 
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possibleto  know  whether  a  is  a  number  or  a  string  when  the  format  call  is  coded,  coerc- 
ing a  to  the  type  required  by  f  by  either  adding  zero  (for  e  or  f  format)  or  concatenating 
(_)  the  null  string  (for  s  format)  should  be  considered. 

index (x,  y) 

returns  the  number  of  the  first  position  in  x  that  any  of  the  characters  from  y  matches.  No 
match  yields  zero. 

trans  (s,  f,  t) 

Translates  characters  of  the  source  s  from  matching  characters  in  f  to  a  character  in  the 
same  position  in  t.  Source  characters  that  do  not  appear  in  f  are  copied  to  the  result.  If  the 
string  f  is  longer  than  t,  source  characters  that  match  in  the  excess  portion  of  f  do  not 
appear  in  the  result. 

substr(s,  start,  width) 

returns  the  sub-string  of  s  defined  by  the  starting  position  and  width. 

mat  ch  ( stri  n  g ,  pattern ) 

mstring(n)  The  pattern  is  a  regular  expression  according  to  the  Basic  Regular  Expression  definition 
(see  regexp(5)).  mstring  returns  the  n-th  (1  <=  n  <=  10)  substring  of  the  subject  that 
occurred  between  pairs  of  the  pattern  symbols  \(  and  \)  for  the  most  recent  call  to 
match.  To  succeed,  patterns  must  match  the  beginning  of  the  string  (as  if  all  patterns 
began  with  ~).  The  function  returns  the  number  of  characters  matched.  For  example: 

match ("al23abl23",    " . *\  ( [a-z] \) ")   ==  6 
mstring (1)    ==  "b" 

File  handling 

open  (name,  file,  function) 
close  (name) 

name  argument  must  be  a  bs  variable  name  (passed  as  a  string).  For  the  open,  the  file 
argument  can  be: 

1.  a  0  (zero),  1,  or  2  representing  standard  input,  output,  or  error  output,  respec- 
tively; 

2.  a  string  representing  a  file  name;  or 

3.  a  string  beginning  with  an  !  representing  a  command  to  be  executed  (via  sh 
-c).  The  function  argument  must  be  either  r  (read),  w  (write),  W  (write 
without  new-line),  or  a  (append).  After  a  close,  name  reverts  to  being  an  ordi- 
nary variable.  If  name  was  a  pipe,  a  wait  ()  is  executed  before  the  close  com- 
pletes (see  wait(2)).  The  bs  exit  command  does  not  do  such  a  wait.  The  ini- 
tial associations  are: 

open  ("get",  0,  "r") 
open  ("put",  1,  "w") 
open("puterr",   2,  "w") 

Examples  are  given  in  the  foil  owing  section. 

access (s,  m) 

executes  access  ()  (see  access(2)). 

ftype(s)  returns  a  single  character  file  type  indication:  f  for  regular  file,  p  for  FIFO  (i.e.,  named 
pipe),  d  for  di rectory,  b  for  block  special,  or  c  for  character  special. 

Tables 

table  (name,  size) 

A  table  in  bs  is  an  associatively  accessed,  single-dimension  array.  "Subscripts"  (called 
keys)  are  strings  (numbers  are  converted).  The  name  argument  must  be  a  bs  variable 
name  (passed  as  a  string).  The  size  argument  sets  the  minimum  number  of  elements  to  be 
allocated,  bs  prints  an  error  message  and  stops  on  table  overflow.  The  result  of  table  is 
name. 

item  (name,  i) 

key()  The  item  function  accesses  tableelements  sequentially  (in  normal  use,  there  is  no  orderly 

progression  of  key  values).  Where  the  item  function  accesses  values,  the  key  function 
accesses  the  "subscript"  of  the  previous  item  call.  It  fails  (or  in  the  absence  of  an 
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interrogate  operator,  returns  null)  if  there  was  no  valid  subscript  for  the  previous 
item  call.  The  name  argument  should  not  be  quoted.  Since  exact  table  sizes  are  not 
defined,  the  interrogation  operator  should  be  used  to  detect  end-of-table;  for  example: 

table ("t",  100) 

#  If  word  contains   "party",    the  following  expression  adds  one 

#  to  the  count  of  that  word: 
++t [word] 

#  To  print  out  the  the  key /value  pairs : 

for  i  =  0,    ?(s  =  item(t,    i) ) ,    ++i  if  key()   put  =  key()_":"_s 

If  the  interrogation  operator  is  not  used,  the  result  of  item  is  null  if  there  are  no  further 
elements  in  the  table.  Null  is,  however,  a  legal  "subscript". 

iskey(name,  word) 

iskey  tests  whether  the  key  word  exists  in  the  table  name  and  returns  one  for  true,  zero 
for  false. 

Odds  and  ends 

eval(s)  Thestring  argument  is  evaluated  as  a  bs  expression.  Thefunction  is  handy  for  converting 
numeric  strings  to  numeric  internal  form,  eval  can  also  be  used  as  a  crude  form  of 
indirection,  as  in: 

name  =  "xyz"  eval ("++"_  name) 

which  increments  the  variable  xyz.  In  addition,  eval  preceded  by  the  interrogation 
operator  permits  the  user  to  control  bs  error  conditions.  For  example: 

?eval ("open(\"x\",   \"XXX\",  \"r\")") 

returns  the  value  zero  if  there  is  no  file  named  XXX  (instead  of  halting  the  user's  program). 
The  foil  owing  executes  a  goto  to  the  label  L  (if  it  exists): 

label="L" 

if  ! (?eval ("goto  "     label))   puterr  =  "no  label" 
plot  (request,  args) 

If  the  tplot  command  is  available,  the  plot  function  produces  output  on  devices  recog- 
nized by  tplot.  The  requests  are  as  follows: 

Call  Function 

plot  (0,  term)  causes  further  plot  output  to  be  piped  into  tplot 

with  an  argument  of  -Tterm.  term  can  be  up  to 
40  characters  in  length. 

plot(l)  "erases"  the  plotter. 

plot  (2,  string)  labelsthe current  point  with  string. 

plot(3,  xl,  yl,  x2,  y2)  draws  the  line  between  (xl,yl)  and  (x2,y2). 

plot(4,  x,y,r)  draws  a  circle  with  center  (x,y)  and  radius  r. 

plot  (5,  xl,  yl,  x2,  y2,  x3,  y3)       draws  an  arc  (counterclockwise)  with  center 

(xl,yl)  and  endpoints  (x2,y2)  and  (x3,y3). 

plot  (6)  is  not  implemented. 

plot  (7,  x,  y)  makes  the  current  point  (x,y). 

plot(8,  x,  y)  draws  a  line  from  the  current  point  to  (x,y). 

plot  (9,  x,  y)  draws  a  point  at  (x,y). 

plot(10,  string)  sets  the  line  mode  to  string. 

plot  (11,  xl,  yl,  x2,  y2)  makes  (xl,yl)  the  lower  left  corner  of  the  plot- 

ting area  and  (x2,y2)  the  upper  right  corner  of 
the  plotting  area. 
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plot  (12,  xl,  yl,  x2,  y2) 


causes  subsequent  x  (y)  coordinates  to  be  multi- 
plied by  xl  (yl)  and  then  added  to  x2  (y2)  before 
they  are  plotted.  The  initial  scaling  is 
plot(12,    1.0,    1.0,    0.0,  0.0). 


Some  requests  do  not  apply  to  all  plotters.  All  requests  except  zero  and  twelve  are  imple- 
mented by  pi  ping  characters  to  tplot. 

Each  statement  executed  from  the  keyboard  re-invokes  tplot,  making  the  results 
unpredictable  if  a  complete  picture  is  not  done  in  a  single  operation.  Plotting  should  thus 
be  done  either  in  a  function  or  a  complete  program,  so  all  the  output  can  be  directed  to 
tplot  in  a  single  stream. 


EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  regular  expressions. 

LC_CTYPE  determines  the  characters  matched  by  character  class  expressions  in  regular  expressions. 

If  LC_COLLATE  or  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  bs  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

I  nternational  Code  Set  Support 

Si  ngle-byte  character  code  sets  are  supported. 

EXAMPLES 

Using  bs  as  a  calculator  ($  is  the  shell  prompt): 

$  bs 

#  Distance    (inches)    light  travels  in  a  nanosecond. 

186000  *  5280  *  12  /  le9 

11.78496 


#  Compound  interest    (6%  for  5  years  on  $1,000) . 
int  =   .06  /  4 
bal  =  1000 

for  i  =  1  5*4  bal  =  bal  +  bal*int 

bal  -  1000 

346.855007 


The  outline  of  a  typical  bs  program: 

#  initialize  things : 
varl  =  1 

open ("read",    "infile",  "r") 

#  compute : 

while  ? (str  =  read) 

next 

#  clean  up : 
close ("read") 

#  last  statement  executed  (exit  or  stop) : 
exit 

#  last  input  line : 
run 


last () 


in  immediate  mode,  last  returns  the  most  recently  computed  value. 


exit 
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I  nput/Output  examples: 

#  Copy  file  oldfile  to  file  newfile. 
open ("read",    "oldfile",  "r") 

open ("write",    "newfile",  "w") 

while  ?  (write  =  read) 

#  close   "read"   and  "write" : 
close ("read") 

close ( "write" ) 

#  Pipe  between  commands . 
open ("Is",    "!ls  *",  "r") 
open("pr",    "!pr  -2  -h  'List'",  "w") 
while  ? (pr  =  Is)  ... 

#  be  sure  to  close   (wait  for)  these: 
close("ls") 

close ( "pr" ) 

WARNINGS 

The  graphics  mode  (plot  ...)  is  not  particularly  useful  unless  the  tplot  command  is  available  on  your 
system. 

bs  is  not  tolerant  of  some  errors.  For  example,  mistyping  a  fun  declaration  is  difficult  to  correct  because 
a  new  definition  cannot  be  made  without  doing  a  clear.  The  best  solution  in  such  a  case  is  to  start  by 
using  the  edit  command. 

SEE  ALSO 

ed(l),  sh(l),  access(2),  printf(3S),  stdio(3S),  lang(5),  regexp(5). 

See  Section  (3M)  for  a  further  description  of  the  mathematical  functions. 

pow()  is  used  for  exponentiation  —  seeexp(3M)); 

bs  uses  the  Standard  I/O  package. 
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NAME 

cal  -  print  calendar 

SYNOPSIS 

cal  [[month  ]  year  ] 

DESCRIPTION 

cal  prints  a  calendar  for  the  specified  year.  If  a  month  is  also  specified,  a  calendar  just  for  that  month  is 
printed.  If  neither  is  specified,  a  calendar  for  the  present  month  is  printed,  year  can  be  between  1  and 
9999.  month  is  a  decimal  number  between  1  and  12.  The  calendar  produced  is  a  Gregorian  calendar. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  set  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used. 

LC_CTYPE  determines  the  locale  for  interpretation  of  sequences  of  bytes  of  text  data  as  characters  (e.g., 
single-  verses  multibyte characters  in  arguments  and  input  files). 

LC_TIME  determines  the  format  and  contents  of  the  calendar. 

TZ  determines  the  timezone  used  to  calculate  the  value  of  the  current  month. 

If  any  internationalization  variable  contains  an  invalid  setting,  cal  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

The  command: 

cal  9  1850 

prints  the  calendar  for  September,  1850  on  the  screen  as  follows: 


September  1850 
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ever,  for  XPG4  the  output  looks  likebelow: 
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WARNINGS 

The  year  is  always  considered  to  start  in  J  anuary  even  though  this  is  historically  naive. 
Bewarethat  cal  83  refers  to  the  early  Christian  era,  not  the  20th  century. 

STANDARDS  CONFORMANCE 

cal:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

calendar  -  reminder  service 

SYNOPSIS 

calendar  [-] 

DESCRIPTION 

calendar  consults  the  file  calendar  in  the  current  directory  and  prints  out  lines  containing  today's  or 
tomorrow's  date  anywhere  in  the  line.  On  weekends,  "tomorrow"  extends  through  Monday. 

When  a  -  command-lineargument  ispresent,  calendar  searches  for  the  file  calendar  in  each  user's 
home  directory,  and  sends  any  positive  results  to  the  user  by  mail  (see  mail(l)).  Normally  this  is  done 
daily  in  the  early  morning  hours  under  the  control  of  cron  (see  cron(lM)).  When  invoked  by  cron, 
calendar  reads  the  first  line  in  the  calendar  file  to  determine  the  user's  environment. 

Language-dependent  information  such  as  spelling  and  date  format  (described  below)  are  determined  by  the 
user-specified  LANG  statement  in  the  calendar  file.  This  statement  should  be  of  the  form 
LANG=  language  where  language  is  a  valid  language  name  (see  lang(5)).  If  this  line  is  not  in  the  calen- 
dar file,  the  action  described  in  the  external  influences  Environment  Variable  section  istaken. 

calendar  is  concerned  with  two  fields:  month  and  day.  A  month  field  can  be  expressed  in  three  different 
formats:  a  string  representing  the  name  of  the  month  (either  fully  spelled  out  or  abbreviated),  a  numeric 
month,  or  an  asterisk  (representing  any  month).  If  the  month  is  expressed  as  a  string  representing  the 
name  of  the  month,  the  first  character  can  be  either  upper-case  or  lower-case;  other  characters  must  be 
lower-case.  The  spelling  of  a  month  name  should  match  the  string  returned  by  calling  nl_langinf  o  ( ) 
(see  nl_langinfo(3C)).  The  day  field  is  a  numeric  value  for  the  day  of  the  month. 

Month-Day  Formats 

If  the  month  field  is  a  string,  it  can  be  followed  by  zero  or  more  blanks.  If  the  month  field  is  numeric,  it 
must  be  followed  by  either  a  slash  (/)  or  a  hyphen  (-).  If  the  month  field  is  an  asterisk  (*),  it  must  be  fol- 
lowed by  a  slash  (/).  The  day  field  can  be  foil  owed  immediately  by  a  blank  or  non-digit  character. 

Day-Month  Formats 

The  day  field  is  expressed  as  a  numeral.  What  follows  the  day  field  is  determined  by  the  format  of  the 
month.  If  the  month  field  is  a  string,  the  day  field  must  be  foil  owed  by  zero  or  one  dot  ( . )  followed  by  zero 
or  more  blanks.  If  the  month  field  is  a  numeral,  the  day  field  must  be  followed  by  either  a  slash  (/)  or  a 
hyphen  (-).  If  the  month  field  is  an  asterisk,  the  day  field  must  be  followed  by  a  slash  (/). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_TIME  determines  the  format  and  contents  of  date  and  time  strings  when  no  LANG  statement  is 
specified  in  the  calendar  file. 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_TIME  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANGisusedas 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  calendar  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  envi  ron (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

Thefollowing  calendar  file  illustrates  several  formats  recognized  by  calendar: 
LANG=en_US . roman8 

Friday,    May  29th:    group  coffee  meeting 

meeting  with  Boss  on  June  3. 

3/30/87  -  quarter  end  review 

4-26  Management   council  meeting  at  1:00  pm 

It  is  first  of  the  month    (  */l  );    status  report  due. 

In  thefollowing  calendar  file,  dates  are  expressed  according  to  European  English  usage: 

LANG=en_GB . roman8 

On  20  Jan.    code  review 
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Jim' s  birthday  is  on  the  3 .  February 

30/3/87  -  quarter  end  review 

26-4  Management   council  meeting  at  1:00  pm 

It  is  first  of  the  month    (  1/*  );    status  report  due. 

WARNINGS 

To  get  reminder  service,  either  your  calendar  must  be  public  information  or  you  must  run  calendar 
from  your  personal  crontab  file,  independent  of  any  calendar  -  run  systemwide.  Note  that  if  you 
run  calendar  yourself,  the  calendar  file  need  not  reside  in  your  home  directory. 

calendar's  extended  idea  of  "tomorrow"  does  not  account  for  holidays. 

This  command  is  likely  to  be  withdrawn  from  X/Open  standards.  Applications  using  this  command  might 
not  be  portable  to  other  vendors'  platforms. 


AUTHOR 

calendar  was  developed  by  AT&T  and  HP. 

FILES 

calendar 
/tmp/cal* 

/usr/lbin/calprog  to  figure  out  today's  and  tomorrow's  dates 

/ usr/bin/ crontab 

/etc/passwd 

SEE  ALSO 

cron(lM),  nl_langinfo(3C),  mail(l),  environ(5). 

STANDARDS  CONFORMANCE 

calendar :  SVI D2,  SVI D3,  XPG2,  XPG3 
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NAME 

cat  -  concatenate,  copy,  and  print  files 

SYNOPSIS 

cat  [-benrstuv]  file  ... 

DESCRIPTION 

cat  reads  each  filein  sequenceand  writes  it  on  the  standard  output.  Thus: 
cat  file 

prints  file  on  the  default  standard  output  device; 

cat  filel  file2  >  file3 
concatenates  filel  and  file2,  and  places  the  result  in  file3. 

If  -  is  appears  as  a  file  argument,  cat  uses  standard  input.  To  combine  standard  input  and  other  files, 
use  a  combination  of  -  and  file  arguments. 

Options 

cat  recognizes  the  following  options: 

-b  Omit  line  numbers  from  blank  lines  when  -n  option  is  specified.  If  this  option  is  specified,  the 
-n  option  is  automatically  selected. 

-e  Print  a  $  character  at  the  end  of  each  line  (prior  to  the  new-line).  If  this  option  is  specified,  the 
-v  option  is  automatically  selected. 

-n    Display  output  lines  preceded  by  line  numbers,  numbered  sequentially  from  1. 

-r  Replace  multiple  consecutive  empty  lines  with  one  empty  line,  so  that  there  is  never  more  than 
one  empty  line  between  lines  containing  characters. 

-s  Silent  option,  cat  suppresses  error  messages  about  non-existent  files,  identical  input  and  out- 
put, and  write  errors.  Normally,  input  and  output  files  cannot  have  identical  names  unless  the 
file  is  a  special  file. 

-t  Print  each  tab  character  as  "I  and  form  feed  character  as  ~L.  If  this  option  is  specified,  the  -v 
option  is  automatically  selected. 

-u    Do  not  buffer  output  (handle character-by-character).  Normally,  output  is  buffered. 

-v  Cause  non-printing  characters  (with  the  exception  of  tabs,  new-lines  and  form-feeds)  to  be 
printed  visibly.  Control  characters  are  printed  using  the  form  "X  (Ctrl-X),  and  the  del  charac- 
ter (octal  0177)  is  printed  as  ~?  (see  ascii (5)).  Single-byte  control  characters  whose  most 
significant  bit  is  set,  are  printed  using  the  form  M-"x,  where  x  is  the  character  specified  by  the 
seven  low  order  bits.  All  other  non-printing  characters  are  printed  as  M-x,  where  x  is  the  char- 
acter specified  by  the  seven  low  order  bits.  This  option  is  influenced  by  the  LC_CTYPE  environ- 
ment variableand  its  corresponding  code  set. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  cat  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 
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I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

Exit  values  are: 

0       Successful  completion. 
>0       Error  condition  occurred. 

EXAMPLES 

To  create  a  zero-length  file,  use  any  of  the  following: 

cat  /dev/null  >  file 
cp  /dev/null  file 
touch  file 

Thefollowing  prints  "I  for  all  the  occurrences  of  tab  character  in  filel 
cat  -t  filel 

To  suppress  error  messages  about  files  that  do  not  exist,  use: 

cat  -s  filel  file2  file3  >  file 

If  file2  does  not  exist,  the  above  command  concatenates  filel  and  file3  without  reporting  the  error  on  file2. 
The  result  is  the  same  if  -s  option  is  not  used,  except  that  cat  displays  the  error  message. 

Toview  non-printable  characters  in  file2,  use: 

cat  -vfile2 

WARNINGS 

Command  formats  such  as 

cat  filel  file2  >  filel 

overwrites  the  data  in  filel  before  the  concatenation  begins,  thus  destroying  the  file.  Therefore,  be  careful 
when  using  shell  special  characters. 

SEE  ALSO 

cp(l),  more(l),  pg(l),  pr(l),  rmnl(l),  ssp(l). 

STANDARDS  CONFORMANCE 

cat:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

cc  -  bundled  C  compiler 

SYNOPSIS 

cc  [options]  files 

DESCRIPTION 

This  manual  page  describes  the  Bundled  C  compiler, 
compliant  HP-UX  manual  page. 

This  cc  accepts  several  types  of  arguments  as  files: 


See  cc(l),  online  only,  for  a  description  of  theANSI- 


.c  Suffix 

Arguments  whose  names  end  with  .c  are  understood  to  beC  source  files.  Each  is  compiled  and 
the  resulting  object  file  is  left  in  a  file  having  the  corresponding  base  name,  .  o  instead  of  .  c. 
However,  if  a  singleC  file  is  compiled  and  linked,  all  in  one  step,  the  .  o  file  is  deleted. 

.s  Suffix 

Arguments  whose  names  end  with  .  s  are  understood  to  be  assembly  source  files  and  are  assem- 
bled, producing  a  .  o  filefor  each  .  s  file. 

.  i  Suffix 

Arguments  whose  names  end  with  .  i  are  assumed  to  be  the  output  of  cpp  (see  the  -P  option 
below).  They  are  compiled  without  invoking  cpp  (see  cpp(l)).  Each  object  file  is  left  in  a  file 
having  the  corresponding  basename,  but  suffixed  with  .o  instead  of  .i. 

-lx  Form 

Arguments  of  the  form  -lx  cause  the  linker  to  search  the  library  libx .  si  or  libx.a  in  an 
attempt  to  resolve  currently  unresolved  external  references.  Because  a  library  is  searched  when 
its  name  is  encountered,  placement  of  a  -1  is  significant.  If  a  file  contains  an  unresolved  exter- 
nal reference,  the  library  containing  the  definition  must  be  pi aced  after  the  file  on  the  command 
line.  See  I d (1)  for  further  details. 

-1 :  libx .  suffix  Form 

Arguments  of  the  form  -1 : libx . suffix  cause  the  linker  to  search  the  library  libx. si  or 
libx .  a  (depending  on  suffix)  in  an  attempt  to  resolve  currently  unresolved  external  references. 
It  issimilartothe-1  option  except  the  current  state  of  the -Wl, -a  option  isnot  important. 

Other  Suffixes 

All  other  arguments,  such  as  those  whose  names  end  with  .  o  or  .a,  are  taken  to  be  relocatable 
object  files  that  are  to  be  included  in  the  link  operation. 

Arguments  and  options  can  be  passed  to  the  compiler  through  theCCOPTS  environment  variable  as  well  as 
on  the  command  line.  The  compiler  reads  the  value  of  CCOPTS  and  divides  these  options  into  two  sets; 
options  that  appear  before  a  vertical  bar(|),  and  options  that  appear  after  the  vertical  bar.  The  first  set  of 
options  are  placed  before  any  of  the  command-line  parameters  to  cc;  the  second  set  of  options  are  placed 
after  the  command-line  parameters  to  cc.  If  the  vertical  bar  is  not  present,  all  options  are  placed  before 
the  command-line  parameters.  For  example  (in  sh(l)  notation), 

CCOPTS="-v    |  -lmalloc" 
export  CCOPTS 
cc  -w  prog . c 

is  equivalent  to 

cc  -v  -w  prog.c  -lmalloc 

When  set,  the  TMPDIR  environment  variablespecifies  a  directory  to  be  used  by  the  compiler  for  temporary 
files,  overriding  the  default  directory  /var/tmp. 

Options 

The  foil  owing  options  are  the  only  options  which  are  recognized  by  the  bundled  C  compiler. 

-c  Suppress  the  link  edit  phase  of  the  compilation,  and  force  an  object  ( .  o)  file  to  be  pro- 

duced for  each  .c  file,  even  if  only  one  program  is  compiled.  Object  files  produced 
from  C  programs  must  be  linked  before  being  executed. 

-C  Prevent  the  preprocessor  from  stripping  C-style comments.  Seecpp(l)  for  details. 
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-Dname=def 
-Dname 


-Idir 

-lx 
-L  dir 

-ooutfile 
-P 

+Rnum 


-S 


-tx,  name 


-Una  me 
-v 

-V 
-w 

-Wx,  arglist 


Define  name  to  the  preprocessor,  as  if  by '^define'.  See  cpp(l)  for  details. 

Run  only  cpp  on  the  named  C  or  assembly  files,  and  send  the  result  to  the  standard 
output. 

Change  the  algorithm  used  by  the  preprocessor  for  finding  include  files  to  also  search 
in  directory  dir.  See cpp(l)  for  details. 

Refer  to  the  DESCRIPTION  section. 

Change  the  algorithm  used  by  the  linker  to  search  for  libx .  si  or  libx .  a.  The  -L 
option  causes  cc  to  search  in  dir  before  searching  in  the  default  locations.  See  I d (1) 
for  details. 

Name  the  output  file  from  the  linker  outfile.  The  default  name  is  a .  out. 

Run  only  cpp  on  the  named  C  files  and  leave  the  result  on  corresponding  files  suffixed 
.i.  The-P  option  is  also  passed  along  to  cpp. 

Allow  only  the  first  num  register  variables  to  actually  have  the  register  class. 
Use  this  option  when  the  register  allocator  issues  the  message: 

out  of  general  registers 

Cause  the  output  of  the  linker  to  be  stripped  of  symbol  table  information.  See  strip(l) 
for  more  details.  The  use  of  this  option  prevents  the  use  of  a  symbolic  debugger  on 
the  resulting  program.  See  I d (1)  for  more  details. 

Compile  the  named  C  files,  and  leave  the  assembly  language  output  on  corresponding 
files  suffixed  .s. 

Substitute  subprocess  x  with  name  where  x  is  one  or  more  of  a  set  of  identifiers  indi- 
cating the  subprocess(es).  This  option  works  in  two  modes:  1)  if  x  is  a  single 
identifier,  name  represents  the  full  path  name  of  the  new  subprocess;  2)  if  x  is  a  set  of 
identifiers,  name  represents  a  prefix  to  which  the  standard  suffixes  are  concatenated 
to  construct  the  ful  I  path  names  of  the  new  subprocesses. 

The  x  can  take  one  or  more  of  the  values: 

p  Preprocessor  (standard  suffix  is  cpp) 

c  Compiler  (standard  suffix  is  ccom) 

a  Assembler  (standard  suffix  is  as) 

1  Linker  (standard  suffix  is  Id) 

Remove  any  initial  definition  of  name  in  the  preprocessor.  See  cpp(l)  for  details. 

Enable  verbose  mode,  which  produces  a  step-by-step  description  of  the  compilation 
process  on  the  standard  error. 

Cause  each  invoked  subprocess  to  print  its  version  information  to  stdout. 
Suppress  warning  messages. 

Pass  the  comma-separated  argument(s)  in  arglist  to  subprocess  x.  The  -W  option 
specification  allows  additional,  implementation-specific  options  to  be  recognized  by  the 
compiler  driver.  For  example, 

-Wl, -a, archive 

causes  the  linker  to  link  with  archive  libraries  instead  of  with  shared  libraries. 
ld(l)for  details. 

The x  can  assume  one  of  the  following  values: 


See 


P 
a 
1 


Preprocessor 

Assembler 

Linker 


Any  other  options  encountered  generate  a  warning  to  standard  error. 

Other  arguments  are  assumed  to  be  C-compatible  object  programs,  typically  produced  by  an  earlier 
cc  run,  or  perhaps  libraries  of  C-compatible  routines.  These  programs,  together  with  the  results  of 
any  compilations  specified,  are  linked  (in  the  order  given)  to  produce  an  executable  program  with  the 
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name  a.  out. 


EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used  as 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  C  (see  lang(5))  is  used.  If  any  internationalization  variable  contains  an  invalid  setting,  cc 
behaves  as  if  all  internationalization  variables  are  set  to  C.  See  environ  (5). 

I  nternational  Code  Set  Support 

Single  byte  and  multibyte  character  code  sets  are  supported. 

DIAGNOSTICS 

The  diagnostics  produced  by  C  itself  are  intended  to  be  self-explanatory.  Occasionally,  messages  may  be 
produced  by  the  preprocessor,  assembler,  or  the  link  editor. 

If  any  errors  occur  before  cc  iscompleted,  a  nonzero  value  is  returned.  Otherwise,  zero  is  returned. 


The  example  below  compiles  the  C  file  prog,  c  to  create  a  prog,  o  file,  then  invokes  the  Id  link  editor  to 
link  prog,  o  and  procedure .  o  with  all  of  the  C  startup  routines  in  /usr/ccs/lib/crtO  .  o  and 
library  routines  from  the  C  library  libc .  si  or  libc .a.  The  resulting  executable  program  is  placed  in 
fileprog: 

cc  prog . c  procedure . o  -o  prog 


Options  not  recognized  by  cc  are  not  passed  on  to  the  link  editor.  Theoption  -Wl,  arg  can  be  used  to  pass 
any  such  option  to  the  link  editor. 

By  default,  the  return  value  from  a  C  program  is  completely  random.  The  only  two  guaranteed  ways  to 
return  a  specific  value  are  to  explicitly  call  exit()  (see  exit(2))  or  leave  the  function  main  ()  with  a 
return  expression;  construct. 


EXAMPLES 


WARNINGS 


FILES 


file . c 
file . o 
a .  out 

/ var / tmp/ ctm* 
/usr/ccs/bin/as 
/usr/ccs/bin/ld 
/usr/ccs/lib/crtO . o 
/usr/lib/libc . a 


/usr/lib/libc . si 


/usr / include 


I  nput  file 
Object  file 

Linked  executable  output  file 
Temporary  files  used  by  the  compiler 
Assembler  (seeas(l)) 
Link  editor  (see  ld(l)) 
Runtime  startup 

Standard  C  library  (archive  version),  see  HP-UX  Reference 
Section  (3) 

Standard  C  library  (shared  version),  see  HP-UX  Reference 
Section  (3) 

Standard  directory  for  #include  files 


Bundled  C  Compiler  Files 

/usr/ ccs/bin/ cc 


C  driver 
C  compiler 

C  compiler  message  catalog 
C  preprocessor 


/usr/ccs/lbin/ccom 


/usr/lib/nls/msg/ $LANG/cc . cat 


/usr/ccs/lbin/cpp 


SEE  ALSO 
System  Tools 


as(l) 
cpp(l) 
ld(l) 
cc(l) 


Translate  assembly  code  to  machi  ne  code. 
Invoke  the  C  language  preprocessor. 
I  nvoke  the  link  editor. 
TheANSI-compliant  C  compiler  on  HP-UX. 
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Miscellaneous 

matherr(3M) 

fpgetround(3M) 

strip(l) 

crt0(3) 

end(3C) 

exit(2) 


Trap  math  errors. 

Floating-point  mode  control  functions. 

Strip  symbol  and  line  number  information  from  an  object  file. 

Execution  startup  routine. 

Symbol  of  the  last  locations  in  program. 

Termination  of  a  process. 


Tutorials  and  Standards  Documents 

B.  W.  Kernighan  and  D.  M.  Ritchie,  TheC  Programming  Language,  Prentice-Hall,  1978. 
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NAME 

cd  -  change  working  directory 

SYNOPSIS 

cd  [directory] 

DESCRIPTION 

If  directory  is  not  specified,  the  value  of  shell  parameter  HOME  is  used  as  the  new  working  directory.  If 
directory  specifies  a  complete  path  starting  with  /,  . ,  or  .  . ,  directory  becomes  the  new  working  directory. 
If  neither  case  applies,  cd  tries  to  find  the  designated  directory  relative  to  one  of  the  paths  specified  by  the 
CDPATH  shell  variable.  CDPATH  has  the  same  syntax  as,  and  similar  semantics  to,  the  PATH  shell  vari- 
able,   cd  must  have  execute  (search)  permission  in  directory. 

cd  exists  only  as  a  shell  built-in  command  because  a  new  process  is  created  whenever  a  command  is  exe- 
cuted, making  cd  useless  if  written  and  processed  as  a  normal  system  command.  Moreover,  different 
shells  provide  different  implementations  of  cd  as  a  built-in  utility.  Features  of  cd  as  described  here  may 
not  be  supported  by  all  the  shells.  Refer  to  individual  shell  manual  entries  for  differences. 

If  cd  is  called  in  a  subshell  or  a  separate  utility  execution  environment  such  as: 

find  .  -type  d  -exec  cd  { } ;   -exec  f oo  { } ; 

(which  invokes  foo  on  accessible  directories)  cd  does  not  affect  the  current  directory  of  the  caller's 
environment.  Another  usage  of  cd  as  a  stand-alone  command  is  to  obtain  the  exit  status  of  the  command. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

Change  the  current  working  directory  to  the  HOME  directory  from  any  location  in  the  file  system: 
cd 

Change  to  new  current  working  directory  foo  residing  in  the  current  directory: 
cd  foo 

or 

cd  ./foo 

Change  to  directory  foobar  residing  in  the  current  directory's  parent  directory: 
cd  . . / foobar 

Change  to  the  directory  whose  absolute  pathname  is  /usr/local/lib/work .  files: 

cd  /usr/local/lib/work . files 
Change  to  the  directory  pro  jl/schedule/staf  f  ing/proposals  relative  to  home  directory: 

cd  $HOME/pro jl/ schedule/staffing/proposals 

VARIABLES 

The  foil  owing  environment  variables  affect  the  execution  of  cd: 

HOME  The  name  of  the  home  directory,  used  when  no  directory  operand  is  specified. 

CDPATH  A  colon-separated  list  of  pathnames  that  refer  to  directories.  If  the  directory  operand 

does  not  begin  with  a  slash  (/)  character,  and  the  first  component  is  not  dot  or  dot- 
dot,  cd  searches  for  directory  relative  to  each  directory  named  in  the  CDPATH  vari- 
able, in  the  order  listed.  The  new  working  directory  is  set  to  the  first  matching  direc- 
tory found.  An  empty  string  in  place  of  a  directory  pathname  represents  the  current 
directory.  If  CDPATH  is  not  set,  it  istreated  as  if  it  was  an  empty  string. 


RETURN  VALUE 

Upon  completion,  cd  exits  with  one  of  the  foil  owing  values: 
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0  The  di  rectory  was  successful  ly  changed. 

>0  An  error  occurred.  The  working  directory  remains  unchanged. 

SEE  ALSO 

csh(l),  pwd(l),  ksh(l),  sh-posix(l),  sh(l),  chdir(2). 

STANDARDS  CONFORMANCE 

cd:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

cdc  -  change  the  delta  commentary  of  an  sees  delta 
SYNOPSIS 

cdc  -r  SID  [-m[mrlist ]]  [-y[ comment ] ]  files 


DESCRIPTION 

The  cdc  command  changes  the  delta  commentary,  for  the  Si  D  specified  by  the  -r  option,  of  each  named 
sees  file. 

Delta  commentary  is  defined  to  be  the  Modification  Request  (MR)  and  comment  information  normally 
specified  via  the  delta(l)  command  (-m  and  -y  options). 

If  a  directory  is  named,  cdc  behaves  as  if  each  file  in  the  directory  were  specified  as  a  named  file,  except 
that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with  s.)  and  unreadable  files  are 
silently  ignored.  If  a  name  of  -  is  given,  the  standard  input  is  read  (see  warnings);  each  line  of  the  stan- 
dard input  istaken  to  be  the  name  of  an  sees  file  to  be  processed. 

Options 

Arguments  to  cdc,  which  can  appear  in  any  order,  consist  of  option  arguments  and  file  names. 

All  of  the  described  option  arguments  apply  independently  to  each  named  file: 

-rSi  D  Used  to  specify  the  S CCS  I  Dentification  (SID)  string  of  a  delta  for  which  the  delta  com- 

mentary is  to  be  changed. 

-m[mrlist]  If  the  sees  file  has  the  v  option  set  (see  admin (1)),  a  list  of  MR  numbers  to  be  added 
and/or  deleted  in  the  delta  commentary  of  the  Si  D  specified  by  the  -r  option  may  be 
supplied.  A  null  MR  list  has  no  effect. 

MR  entries  are  added  to  the  list  of  mrs  in  the  same  manner  as  that  of  delta(l).  To 
delete  an  MR,  precede  the  MR  number  with  the  character  !  (see  examples).  If  the 
MR  to  be  deleted  is  currently  in  the  list  of  mrs,  it  is  removed  and  changed  into  a  "com- 
ment" line.  A  list  of  all  deleted  mrs  is  placed  in  the  comment  section  of  the  delta  com- 
mentary and  preceded  by  a  comment  line  stating  that  they  were  deleted. 

If  -m  is  not  used  and  the  standard  input  is  a  terminal,  the  prompt  MRs?  is  issued  on 
the  standard  output  before  the  standard  input  is  read;  if  the  standard  input  is  not  a 
terminal,  no  prompt  is  issued.  TheMRs?  prompt  always  precedes  the  comments? 
prompt  (see-y  option). 

mrs  in  a  list  are  separated  by  blanks  and/or  tab  characters.  An  unescaped  new-line 
character  terminates  the  mrs  list. 

Note  that  if  the  v  option  has  a  value  (see  admin (1)),  it  is  treated  as  the  name  of  a  pro- 
gram (or  shell  procedure)  that  validates  the  correctness  of  the  MR  numbers.  If  a  non- 
zero exit  status  is  returned  from  the  MR  number  validation  program,  cdc  terminates 
and  the  delta  commentary  remains  unchanged. 

-y[comment]  Arbitrary  text  used  to  replace  the  comment  or  comments  already  existing  for  the  delta 
specified  by  the  -r  option.  Previous  comments  are  kept  and  preceded  by  a  comment 
line  stating  that  they  were  changed.  A  null  comment  has  no  effect. 

If  -y  is  not  specified  and  the  standard  input  is  a  terminal,  the  prompt  comments? 
is  issued  on  the  standard  output  before  standard  input  is  read;  if  standard  input  is  not 
a  terminal,  no  prompt  is  issued.  An  unescaped  new-line  character  terminates  the 
comment  text. 

The  exact  permissions  necessary  to  modify  the  sees  file  are  documented  in  get(l).  Simply  stated,  they  are 
either: 

•  I  f  you  made  the  delta,  you  can  change  its  delta  commentary,  or 

•  If  you  own  the  file  and  directory,  you  can  modify  the  delta  commentary. 


EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 
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I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Usesccshelp(l)  for  explanations. 

EXAMPLES 

Addbl78-12345  and  bl79-00001  to  the  MR  list,  remove  bl77-54321  from  the  MR  list,  and  add  the 
comment  trouble  to  delta  1.6  of  s  .  file : 

cdc  -rl.6  -m"bl78-12345   !bl77-54321  bl79-00001"    -ytrouble  s . f ile 

The  foil  owing  does  the  same  thing: 
cdc  -rl.6  s.file 

MRs?    !bl77-54321  bl78-12345  bl79-00001 
comments?  trouble 

WARNINGS 

If  sees  file  names  are  supplied  to  the  cdc  command  via  the  standard  input  (-  on  the  command  line),  the 
-m  and  -y  options  must  also  be  used. 

FILES 

x-file  Seedelta(l). 
z-file  Seedelta(l). 

SEE  ALSO 

admin(l),  delta(l),  get(l),  sccshelp(l),  prs(l),  sccsfile(4),  rcsfile(4),  acl(5),  rcsintro(5). 
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NAME 

chad  -add,  modify,  delete,  copy,  or  summarize  access  control  lists  (ACLs)  of  files 

SYNOPSIS 

/usr/bin/chacl  acl  file  ... 

chacl  -r  acl  file  ... 

chad  -d  aclpatt  file  ... 

chacl  -f  fromfile  tofile  ... 

chacl  -[z  |  Z  |  F]  file... 

DESCRIPTION 

chacl  extends  the  capabilities  of  chmod(l),  by  enabling  the  user  to  grant  or  restrict  file  access  to  addi- 
tional specific  users  and/or  groups.  Traditional  file  access  permissions,  set  when  a  file  is  created,  grant  or 
restrict  access  to  the  file's  owner,  group,  and  other  users.  These  file  access  permissions  (eg.,  rwxrw-r — ) 
are  mapped  into  three  base  access  control  list  entries:  one  entry  for  the  file's  owner  (u .  %,  mode),  one  for 
the  file's  group  (% .  g,  mode),  and  one  for  other  users  (% .  %,  mode). 

chacl  enables  a  user  to  designate  up  to  thirteen  additional  sets  of  permissions  (called  optional  access  con- 
trol list  (acl)  entries)  which  are  stored  in  the  access  control  list  of  the  file. 

To  use  chacl ,  the  owner  (or  superuser)  constructs  an  acl ,  a  set  of  (user. group,  mode)  mappings  to  associate 
with  one  or  more  files.  A  specific  user  and  group  can  be  referred  to  by  either  name  or  number;  any  user 
(u),  group  (g),  or  both  can  be  referred  to  with  a  %  symbol,  representing  any  user  or  group.  The  ©symbol 
specifies  the  file's  owner  or  group. 

Read,  write,  and  execute/search  (rwx)  modes  are  identical  to  those  used  by  chmod;  symbolic  operators  (op) 
add  (+),  remove  (-),  or  set  (=)  access  rights.  The  entire  acl  should  be  quoted  if  it  contains  whitespace  or 
special  characters.  Although  two  variants  for  constructing  the  acl  are  available  (and  fully  explained  in 
acl  (5)),  the  foil  owing  syntax  is  suggested: 

entry [,  entry]  ... 

where  the  syntax  for  an  entry  is 

u.g  op  mode[ op  mode]  ■■■ 

By  default,  chacl  modifies  existing  acls.  It  adds  acl  entries  or  modifies  access  rights  in  existing  acl 
entries.  If  acl  contains  an  acl  entry  already  associated  with  a  file,  the  entry's  mode  bits  are  changed  to  the 
new  value  given,  or  are  modified  by  the  specified  operators.  If  the  file's  acl  does  not  already  contain  the 
specified  entry,  that  acl  entry  is  added,  chacl  can  also  remove  all  access  to  files.  Giving  it  a  null  acl 
argument  means  either  "no  access"  (when  using  the  -r  option)  or  "no  changes." 

For  a  summary  of  the  syntax,  run  chacl  without  arguments. 

If  file  is  specified  as-,  chacl  reads  from  standard  input. 

Options 

chacl  recognizes  the  following  options: 

-r  Replace  old  acls  with  the  given  acl.  All  optional  acl  entries  are  first  deleted  from  the 

specified  files's  acls,  their  base  permissions  are  set  to  zero,  and  the  new  acl  is  applied.  If 
acl  does  not  contain  an  entry  for  the  owner  (u .  %),  the  group  (% .  g),  or  other  (%  .  %)  users  of 
a  file,  that  base  acl  entry's  mode  is  set  to  zero  (no  access).  The  command  affects  all  of  the 
file's  acl  entries,  but  does  not  change  the  file's  owner  or  group  id. 

In  chmod(l),  the  "modify"  and  "replace"  operations  are  distinguished  by  the  syntax  (string 
or  octal  value).  There  is  no  corollary  for  ACLs  because  they  have  a  variable  number  of 
entries.  Hence  chacl  modifies  specific  entries  by  default,  and  optionally  replaces  all 
entries. 

-d  Delete  the  specified  entries  from  the  ACLs  on  all  specified  files.  The  aclpatt  argument  can 

be  an  exact  acl  or  an  acl  pattern  (see  acl  (5)).  chacl  -d  updates  each  file's  acl  only  if 
entries  are  deleted  from  it. 

If  you  attempt  to  delete  a  base  acl  entry  from  any  file,  the  entry  remains  but  its  access 
mode  is  set  to  zero  (no  access).  If  you  attempt  to  delete  a  non-existent  acl  entry  from  a  file 
(that  is,  if  an  acl  entry  pattern  matches  no  acl  entry),  chacl  informs  you  of  the  error, 
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continues,  and  eventually  returns  non-zero, 
-f  f romf i  I  e  tof i  I  e 

Copy  the  ACL  from  fromfileto  the  specified  tofile,  transferring  ownership,  if  necessary  (see 
acl  (5),  chown(2),  or  chownacl  (3C)).  fromfilecan  be  -  to  represent  standard  input. 

This  option  implies  the  -r  option.  If  the  owner  and  group  of  fromfileare  identical  to  those 
of  tofile,  chad  -f  is  identical  to: 

chacl  -r   'lsacl  f romf ile 1  tofile  ... 

To  copy  an  ACL  without  transferring  ownership,  the  above  command  is  suggested  instead  of 
chacl  -f. 

-z  Delete  ("zap")  all  optional  entries  in  the  specified  file's  acls,  leaving  only  base  entries. 

-Z  Delete  ("zap")  all  optional  entries  in  the  specified  file's  acls,  and  set  the  access  modes  in  all 

base  entries  to  zero  (no  access).  This  is  identical  to  replacing  the  old  ACL  with  a  null  ACL: 

chacl  -r  '  '   file  ... 

or  using  chmod(l),  which  deletes  optional  entries  asa  side  effect: 
chmod  0  file  ... 

-F  Incorporate  ("fold")  optional  ACL  entries  into  base  ACL  entries.  The  base  ACL  entry's  per- 

mission bits  are  altered,  if  necessary,  to  reflect  the  caller's  effective  access  rights  to  the  file; 
all  optional  entries,  if  any,  are  deleted. 

For  ordinary  users,  only  the  access  mode  of  the  owner  base  ACL  entry  can  be  altered. 
Unlike  getaccess ,  the  write  bit  is  not  turned  off  for  a  file  on  a  read-only  file  system  or  a 
shared-text  program  being  executed  (see  getaccess (1)). 

For  super-users,  only  the  execute  mode  bit  in  the  owner  baseACL  entry  might  be  changed, 
only  if  the  file  is  not  an  regular  file  or  if  an  execute  bit  is  not  already  set  in  a  baseACL  entry 
mode,  but  is  set  in  an  optional  ACL  entry  mode. 

acl  also  can  be  obtained  from  a  string  in  a  file: 

chacl   'cat  file1  files  ... 

Using  @in  acl  to  represent  "file  owner  or  group"  can  cause  chacl  to  run  more  slowly  because  it  must 
reparsetheACL  for  each  file  (except  with  the  -d  option). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 
If  any  internationalization  variable  contains  an  invalid  setting,  chacl  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

RETURN  VALUE 

If  chacl  succeeds,  it  returns  a  value  of  zero. 

If  chacl  encounters  an  error  before  it  changes  any  file's  acl,  it  prints  an  error  message  to  standard  error 
and  returns  1.  Such  errors  include  invalid  invocation,  invalid  syntax  of  acl  (aclpatt),  a  given  user  name  or 
group  name  is  unknown,  or  inability  to  get  an  acl  from  fromfile  with  the  -f  option. 

If  chacl  cannot  execute  the  requested  operation,  it  prints  an  error  message  to  standard  error,  continues, 
and  later  returns  2.  This  includes  cases  when  a  file  does  not  exist,  a  file's  acl  cannot  be  altered,  more  acl 
entries  would  result  than  are  allowed,  or  an  attempt  is  made  to  delete  a  non-existing  acl  entry. 

EXAMPLES 

Thefollowing  command  adds  read  access  for  user  jpc  in  any  group,  and  removes  write  access  for  any  user 
in  the files's  groups,  for  files  xandy. 

chacl   "jpc.%+r,    %.@-w"  x  y 

This  command  replaces  the  acl  on  the  file  open  as  standard  input  and  on  file  test  with  one  which  only 
allows  the  file  owner  read  and  write  access. 
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chad  -r  '  (§.%,rw-)'    -  test 

Delete  from  file  myfile  the  specific  access  rights,  if  any,  for  user  165  in  group  13.  Note  that  this  is 
different  from  adding  an  ACL  entry  that  restricts  access  for  that  user  and  group.  The  user's  resulting  access 
rights  depend  on  the  entries  remaining  in  the  ACL.  The  command  also  deletes  all  entries  for  user  jpc  that 
have  a  read  bit  turned  on  (the  asterisk  can  be  used  as  a  wildcard  in  the  ACL  pattern  for  user,  group,  or 
access  mode): 

chad  -d  '165.13,    jpc.*+r'  myfile 

Copy  the  ACL  from  oldfile  to  slow/hare  and  fast/tortoise. 

chacl  -f  oldfile  slow/hare  fast/tortoise 

Delete  the  optional  ACL  entries,  if  any,  on  the  file  open  as  standard  input, 
chacl  -z  - 

Deny  all  access  to  all  files  in  the  current  directory  whose  names  start  with  a,  b,  or  c: 

chacl  -Z  [a-c]* 
I  ncorporate  the  optional  ACL  entries  of  a  file  (fun.  stuff )  into  the  base  ACL  entries: 

chacl  -F  fun. stuff 

WARNINGS 

An  ACL  string  cannot  contain  more  than  16  unique  entries,  even  though  converting  ©symbols  to  user  or 
group  names  and  combining  redundant  entries  might  result  in  fewer  than  16  entries  for  some  files. 

DEPENDENCIES 

chacl  will  fail  when  the  target  file  resides  on  a  file  system  which  does  not  support  ACLs. 

NFS 

Only  the  — F  option  is  supported  on  remote  files. 

AUTHOR 

chacl  was  developed  by  HP. 

SEE  ALSO 

chmod(l),  getaccess(l),  Isacl(l),  getacl(2),  setacl(2),  acl(5),  glossary(9). 
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NAME 

chatr  -  change  program's  internal  attributes 

SYNOPSIS 

PA32  SOM  chatr 

chatr  [-nqsMN]  [-1  library]  [-B  mode]  [+b  flag]  [+es  flag]  [+gst  flag]  [+gstbuckets  size] 
[+gstsize  size]  [+k  flag]  [+1  library]  [+pd  size]  [+pi  size]  [+plabel_cache  flag] 
[+q3p  flag]  [+q4p  flag]  [+r  flag]  [+s  flag]  [+z  flag]  file  ... 

PA64  ELF  chatr 

There  are  two  possible  syntactic  forms  that  can  be  used  to  invoke  PA64  chatr. 

FORMAT  1:  The  first  syntactic  form,  which  is  compatible  with  the  SOM  chatr,  is  used  for  back- 
ward compatibility,  and  for  easy  manipulation  of  ordinary  files  that  only  have  a  single  text  and  a 
single  data  segment: 

chatr  [-nqs]  [-1  library]  [-B  mode]  [+b  flag]  [+cd  flag]  [+ci  flag]  [+es  flag]  [+gst  flag] 
[+gstsize  size]  [+k  flag]  [+1  library]  [+md  flag]  [+mi  flag]  [+pd  size]  [+pi  size]  [+s 
flag]  [+z  flag]  file  ... 

FORMAT  2:  The  second  syntactic  form  provides  the  ability  to  explicitly  specify  segments  to  be 
modified: 

chatr  [-s]  [-B  mode]  [+c  flag]  [+dz  flag]  [+k  flag]  [+m  flag]  [+p  size]  [+r  flag]  [+s  flag] 
[+si  index  |  +sa  address  |  +sall  ]  [+z  flag]  file  ... 

DESCRIPTION 

chatr  allows  you  to  change  a  program's  internal  attributes  for  32-bit  mode  SOM  and  64-bit  mode  ELF 
files. 

Upon  completion,  chatr  prints  the  file's  old  and  new  values  to  standard  output  unless  -s  isspecified. 

The  +pd  and  +pi  options  only  provide  a  hint  for  the  virtual  memory  page  size.  The  actual  page  sizes 
may  vary.  Under  certain  conditions,  page  size  hints  of  L  may  result  in  better  performance,  depending  on 
the  specific  memory  requirements  of  the  application. 

The  performance  of  some  applications  may  benefit  from  static  branch  prediction,  others  may  not.  The  +r 
option  providesa  hint  for  using  or  avoiding  this  feature. 

The  +gst  and  related  options  provide  performance  enhancements  through  use  of  global  symbol  table 
which  improves  searching  for  exported  symbols.  See  did. si  (5)  and  the  HP-UX  Linker  and  Libraries  Online 
User  Guidefor  more  information. 

COMMON  OPTIONS  FOR  PA32  SOM  AND  PA64ELF  (FORMAT  1)  chatr 

chatr,  by  default,  prints  each  file's  magic  number  and  file  attributes  to  the  standard  output. 

-1  library      Indicate  that  the  specified  shared  library  is  subject  to  run-time  path  lookup  if  directory 
path  lists  are  provided  (see  +s  and +b). 

-n  Change  file  from  demand-loaded  (DEMAND_MAGIC  )  to  shared  (SHARE_MAGIC  )  (Ignored 


in  PA64  FORMAT  1.) 


-q 


Change  file  from  shared  (SHARE_MAGIC  )  to  demand-loaded  (DEMAND_MAGIC  ).  (Ignored 
in  PA64  FORMAT  1.) 


-s 


Perform  its  operation  silently.  (Availablewith  the  PA64  FORMAT  2  command.) 


-B  mode 


Select  run-time  binding  behavior  mode  of  a  program  using  shared  libraries.  You  must 
specify  one  of  the  major  binding  modes  immediate  or  deferred.  One  or  more  of  the 
binding  modifiers  nonfatal,  verbose,  or  restricted  can  also  be  specified,  each 
with  a  separate  option.  See  the  HP-UX  Linker  and  Libraries  User's  Guide  manual  for  a 
description  of  binding  modes.  (Availablewith  the  PA64  FORMAT  2  command.) 


+b  flag 


Control  whether  the  embedded  path  list  stored  when  the  program  (if  any)  was  built  can  be 
used  to  locate  shared  libraries  needed  by  the  program.  The  two  flag  values,  enable  and 
disable,  respectively  enable  and  disable  use  of  the  embedded  path  list.  See  the  +s 
option.  You  can  use  the  +b  option  to  enable  the  embedded  path  for  filter  libraries. 


+es  flag 


Control  the  ability  of  user  code  to  execute  from  stack  with  the  flag  values,  enable  and 
disable.  See  the  Restricting  Execute  Permission  on  Stacks  section  below  for  additional 
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information  related  to  security  issues. 

+gst  flag  Control  whether  the  global  symbol  table  hash  mechanism  is  used  to  look  up  values  of  sym- 
bol import/export  entries.  The  two  flag  values,  enable  and  disable,  respectively 
enable  and  disable  use  of  the  global  symbol  table  hash  mechanism.  The  default  is  dis- 
able. 

+gstsize  size 

Request  a  particular  hash  array  size  using  the  global  symbol  table  hash  mechanism.  The 
value  can  vary  between  1  and  MAXINT.  The  default  value  is  1103.  Use  this  option  with 
+gst  enable. 

+k  flag  Request  kernel  assisted  branch  prediction.  The  flags  enable  and  disable  turn  this 

request  on  and  off,  respectively.  (Availablewith  the  PA64  FORMAT  2  command.) 

+1  library  I  ndicate  that  the  specified  shared  library  is  not  subject  to  run-time  path  lookup  if  directory 
path  lists  are  provided  (see  +s  and +b). 

Request  a  particular  virtual  memory  page  size  that  should  be  used  for  data.  Sizes  of  4K, 
16K,  64K,  256K,  1M,  4M,  16M,  64M,  256M,  and  L  are  supported.  A  size  of  L  will  result 
in  usingthe  largest  page  size  available.  Theactual  page  size  may  vary  if  the  requested  size 
cannot  be  fulfil  led. 

Request  a  particular  virtual  memory  page  size  that  should  be  used  for  instructions.  Seethe 
+pd  option  for  additional  information. 

Request  static  branch  prediction  when  executing  this  program.  The  flags  enable  and 
disable  turn  this  request  on  and  off,  respectively.  (Availablewith  the  PA64  FORMAT  2 
command.) 

Control  whether  the  directory  path  list  specified  with  the  SHLIB_PATH  environment 
variable  can  be  used  to  locate  shared  libraries  needed  by  the  program.  The  two  flag  values, 
enable  and  disable,  respectively  enable  and  disable  use  of  the  environment  variable. 
If  both  +s  and  +b  are  used,  their  relative  order  on  the  command  line  indicates  which  path 
list  will  be  searched  first.  See  the  +b  option.  (Availablewith  the  PA64  FORMAT  2  com- 
mand.) 

Enablelazy  swap  on  all  data  segments  (using  PA32  chatr  or  PA64  chatr  FORMAT  1)  or  on  a 
specific  segment  (using  PA64  ELF  chatr  FORMAT  2).  May  not  be  used  with  non-data  seg- 
ments. 

OPTIONS  FOR  PA32  SOM  chatr  ONLY 

-M  Change  file  from  EXEC_MAGIC  to  SHMEM_MAGIC .  (This  option  is  an  interim  solution 

until  64-bit  addressability  is  availablewith  a  true  64-bit  kernel.  Seethe  "chatr  and  MAGIC 
Numbers"  and  "Using  SHMEMMAGIC"  sections  below.) 

-N  Change  file  from  SHMEM_MAGIC  to  EXEC_MAGIC .  (This  option  is  an  interim  solution 

until  64-bit  addressability  is  availablewith  a  true  64-bit  kernel.  Seethe  "chatr  and  MAGIC 
Numbers"  and  "Using  SHMEM  MAGIC"  sections  below.) 

+gstbuckets  size 

Request  a  particular  number  of  buckets  per  entry  using  the  global  symbol  table  hash 
mechanism.  The  value  can  vary  between  1  and  MAXINT.  The  default  value  is  3.  Usethis 
option  with  +gst  enable. 

+plabel_cache  flag 

Control  the  use  of  the  pi abel  caching  mechanism.  Theflags  enable  and  disable  turn 
this  request  on  and  off,  respectively.  The  default  is  disable.  Usethis  option  with  +gst 
enable. 

This  option  is  effective  with  C++.  In  C++ applications,  the  dynamic  loader  needs  to  repeti- 
tively access  PLABEL  information  (import  stub).  In  order  to  make  this  access  faster,  the 
dynamic  loader  uses  the  global  symbol  tablestructureto  also  contain  PLABEL  entries.  This 
behavior  is  enabled  when  the  PLABEL  CACHE  flag  is  set  in  the  dl  header  structure 
(enabled  Id  +plabel_cache  enable  a. out  or  chatr  +plabel_cache 
enable  a. out). 

+q3p  flag  Control  the  flag  bit  setting  to  indicate  how  32-bit  processes  use  the  third  quadrant  as  data 
space. 


+pd  size 

+pi  size 
+r  flag 

+s  flag 
+z 
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The  enable  flag  sets  the  flag  bit  to  indicate  that  32-bit  processes  use  the  third  quadrant 
as  a  private  data  space.  By  setting  the  bit,  the  private  data  space  increases  from  1.9GB  to 
2.85GB  for  32-bit  processes. 

The  disable  flag  unsets  the  bit,  which  returns  the  third  quadrant  to  the  default  state,  in 
which  it  is  used  for  shared  memory. 

This  flag  mechanism  differs  from  how  to  set  usage  for  the  first  and  second  quadrants.  Set 
these  values  by  using  the  magic  number  of  the  executable.  (Seethe  -M  and  -N  options.) 

+q4p  flag       Control  the  flag  bit  setting  to  indicate  how  32-bit  processes  use  the  third  and  fourth  qua- 
drant as  data  space. 

The  enable  flag  sets  the  flag  bit  to  indicate  that  32-bit  processes  use  the  fourth  quadrant 
as  a  private  data  space.  By  setting  the  +q4p  flag  bit,  the  private  data  space  increases  from 
1.9GB  to  3.8GB  for  32-bit  processes.  When  you  set  the  fourth  quadrant  for  private  data 
space,  the  third  quadrant  is  automatically  set  for  use  as  private  data  space,  ignoring  the 
current  +q3p  value. 

The  disable  flag  unsets  the  flag  bit,  which  returns  the  fourth  quadrant  to  the  default 
state,  in  which  it  is  used  for  shared  memory.  With  +q4p  disable,  the  value  of  the 
+q3p  flag  controls  whether  the  third  quadrant  is  used  as  a  private  data  space  or  for  shared 
memory. 

This  flag  mechanism  differs  from  how  to  set  usage  for  the  first  and  second  quadrants.  Set 
these  values  by  using  the  magic  number  of  the  executable.  (Seethe  -M  and  -N  options.) 

OPTIONS  FOR  PA64ELF  chatr 

PA64  ELF  chatr  is  similar  to  SOM  chatr  but  supports  new  options  (and  obsoletes  others). 

New  options: 


OPTIONS  FOR  PA64  ELF  chatr    (FORMAT  1) 

+cd  Set  the  code  bit  for  the  file's  data  segment(s). 

+ci  Set  the  code  bit  for  the  file's  text  segments(s). 

+md  Set  the  modification  bit  for  the  file's  data  segment(s). 

+mi  Set  the  modification  bit  for  the  file's  text  segment(s). 

OPTIONS  FOR  PA64  ELF  chatr    (FORMAT  2) 

With  common  options:  -s,  -B  mode,  +k  flag,  +r  flag,  +s  flag,  +z  flag. 

+c  Set  the  code  bit  for  a  specified  segment. 

+dz  Enable  or  disable  lazy  swap  allocation  for  dynamically  allocated  segments  (such  as  the  stack 
or  heap). 

+m  Set  the  modification  bit  for  a  specified  segment. 

+p  Set  the  page  size  for  a  specified  segment. 

+sa  Specify  a  segment  using  an  address  for  a  set  of  attribute  modifications. 

+sall  Useall  segments  in  the  filefor  a  set  of  attribute  modifications. 

+si  Specify  a  segment  using  a  segment  index  number  for  a  set  of  attribute  modifications. 


chatr  and  MAGIC  Numbers 
Theterm  shared  applies  to  the  magic  number  SHARE_MAGIC  whiletheterm  demand-loaded  applies  to 
the  magic  number  DEMAND_MAGIC .  See  magic(4)  and  the  HP-UX  Linker  and  Libraries  Online  User 
Guidefor  more  information. 

chatr  labels  the  foil  owing  type  of  executables  in  output. 
SHARE_MAGIC:      shared  executable 
DEMAND_MAGIC :    demand  load  executable 
EXEC_MAGIC:        normal  executable 
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SHMEM_MAGIC:      normal  SHMEM_MAGIC  executable 
The  linker  produces  SHARE_MAGIC  executables  by  default. 

Using  SHMEM  MAGIC 

SHMEM_MAGIC  is  an  i nteri m  sol ution  until  64-bit  addressability  is  availablewith  a  true  64-bit  kernel. 

SHMEM_MAGIC  will  not  be  supported  on  future  HP  implementations  of  64-bit  architectures  (beyond 
PA2.0).  Programs  that  need  larger  than  1.75  GB  of  shared  memory  on  those  architectures  will  have  to  be 
recompiled  (as  64-bit  executables)  for  those  architectures. 

Programs  that  are  compiled  as  64-bit  executables  on  any  64-bit  HP  implementation  (including  PA  2.0)  can- 
not be  marked  as  SHMEM_MAGIC  nor  do  they  need  to  be  as  they  will  already  have  access  to  more  than 
1.75  GB  of  shared  memory. 

The  additional  1  GB  of  shared  memory  that  is  available  over  other  types  of  executables  can  be  availed  of 
only  for  system  V  shared  memory  and  not  other  forms  of  shared  memory  (like  memory  mapped  files). 

Restricting  Execute  Permission  on  Stacks 

A  frequent  or  common  method  of  breaking  intosystems  is  by  maliciously  overflowing  buffers  on  a  program's 
stack,  such  as  passing  unusually  long,  carefully  chosen  command  line  arguments  to  a  privileged  program 
that  does  not  expect  them.  Malicious  unprivileged  users  can  use  this  technique  to  trick  a  privileged  pro- 
gram into  starting  a  su peruser  shell  for  them,  or  to  perform  similar  unauthorized  actions. 

One  simple  yet  highly  effective  way  to  reduce  the  risk  from  this  type  of  attack  is  to  remove  the  execute  per- 
mission from  a  program's  stack  pages.  This  improves  system  security  without  sacrificing  performance  and 
has  no  negative  effects  on  the  vast  majority  of  legitimate  applications.  The  changes  described  in  this  sec- 
tion only  affect  the  very  small  number  of  programs  that  try  to  execute  (or  are  tricked  into  executing) 
instructions  located  on  the  program's  stack(s). 

If  the  stack  protection  feature  described  in  this  section  is  enabled  for  a  program  and  that  program  attempts 
to  execute  code  from  its  stack(s),  the  HP-UX  kernel  will  terminate  the  program  with  a  SIGKILL  signal, 
display  a  message  referring  to  this  manual  page  section,  and  log  an  error  message  to  the  system  message 
log  (use  dmesg  to  view  the  error  message).  The  message  logged  by  the  kernel  is: 

WARNING:  UID  #  may  have  attempted  a  buffer  overflow  attack.  PID  # 
(program_name)  has  been  terminated.  See  the  ' +es  enable'  option  of 
chatr(l) . 

If  you  see  one  of  these  messages,  check  with  the  program's  owner  to  determine  whether  this  program  is  leg- 
itimately executing  code  from  its  stack.  If  it  is,  you  can  use  one  or  both  of  the  methods  described  below  to 
make  the  program  functional  again.  If  the  program  is  not  legitimately  executing  code  from  its  stack,  you 
should  suspect  malicious  activity  and  take  appropriate  action. 

HP-UX  provides  two  options  to  permit  legitimate  execution  from  a  program's  stack(s).  Combinations  of 
these  two  options  help  make  site-specific  tradeoffs  between  security  and  compatibility. 

The  first  method  is  the  use  of  the  +es  option  of  chatr  and  affects  individual  programs.  It  is  typically 
used  to  specify  that  a  particular  binary  must  be  able  to  execute  from  its  stack,  regardless  of  the  system 
default  setting.  This  allows  a  restrictive  system  default  while  not  preventing  legitimate  programs  from 
executing  code  on  their  stack(s).  Ideally  this  option  should  be  set  (if  needed)  by  the  program's  provider,  to 
minimize  the  need  for  manual  intervention  by  whomever  installs  the  program. 

An  alternate  method  is  setting  the  kernel  tunable  parameter,  executable_stack,  to  set  a  system-wide 
default  for  whether  stacks  are  executable.  Setting  the  executable_stack  parameter  to  1  (one)  with 
sam  (see  sam(livi))  tells  the  HP-UX  kernel  to  allow  programs  to  execute  on  the  program  stack(s).  Use  this 
setting  if  compatibility  with  older  releases  is  more  important  than  security.  Setting  the 
executable_stack  parameter  to  0  (zero),  the  recommended  setting,  is  appropriate  if  security  is  more 
important  than  compatibility.  This  setting  significantly  improves  system  security  with  minimal,  if  any, 
negative  effects  on  legitimate  applications. 

Combinations  of  these  settings  may  be  appropriate  for  many  applications.  For  example,  after  setting 
executable_stack  to  0,  you  may  find  that  one  or  two  critical  applications  no  longer  work  because  they 
have  a  legitimate  need  to  execute  from  their  stack(s).  Programs  such  as  simulators  or  interpreters  that  use 
self-modifying  code  are  examples  you  might  encounter.  To  obtain  the  security  benefits  of  a  restrictive  sys- 
tem default  while  still  letting  these  specific  applications  run  correctly,  set  executable_stack  to  0,  and 
run  chatr  +es  enable  on  the  specific  binaries  that  need  to  execute  code  from  their  stack(s).  These 
binaries  can  be  easily  identified  when  they  are  executed,  because  they  will  print  error  messages  referring  to 
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this  manual  page. 

Thepossiblesettingsfor  executable_stack  are  as  follows: 

executable_stack  =  0 

A  setting  of  0  causes  stacks  to  be  non-executable  and  is  strongly  preferred  from  a  security  per- 
spective. 

executable_stack  =  1  (default) 

A  setting  of  1  (the  default  value)  causes  all  program  stacks  to  be  executable,  and  is  safest  from  a 
compatibility  perspective  but  is  the  least  secure  setting  for  this  parameter. 

executable_stack  =  2 

A  setting  of  2  is  equivalent  to  a  setting  of  0,  except  that  it  gives  non-fatal  warnings  instead  of  ter- 
minating a  process  that  is  trying  to  execute  from  its  stack.  Using  this  setting  is  helpful  for  users 
to  gain  confidence  that  using  a  value  of  0  will  not  hurt  their  legitimate  applications.  Again,  there 
is  less  security  protection. 

The  table  below  summarizes  the  results  from  using  the  possible  combinations  of  chatr  +es  and 
executable_stack  when  executing  from  the  program's  stack.  Running  chatr  +es  disable 
relies  solely  on  the  setting  of  the  executable_stack  kernel  tunable  parameter  when  deciding  whether 
or  not  to  grant  execute  permission  for  stacks  and  is  equivalent  to  not  having  run  chatr  +es  on  the 
binary. 


chatr  -tes 

executable  stack 

ACTION 

enable 

disable  or  chatr  is  not  run 

1 
1 

program  runs  normally 
program  runs  normally 

enable 

disable  or  chatr  is  not  run 

0 
0 

program  runs  normally 
program  is  killed 

enable 

disable  or  chatr  is  not  run 

2 
2 

program  runs  normally 
program  runs  normally 
with  warning  displayed 

RETURN  VALUE 

chatr  returns  zero  on  success.  If  the  command  line  contents  is  syntactically  incorrect,  or  one  or  more  of 
the  specified  files  cannot  be  acted  upon,  chatr  returns  information  about  the  files  whose  attributes  could 
not  be  modified.  If  no  files  are  specified,  chatr  returns  decimal  255. 

Illegal  options 

For  PA32  chatr,  if  you  use  an  illegal  option,  chatr  returns  the  number  of  words  in  the  command  line. 
For  example, 

chatr  +b  enable  +xyz  enable  returns  5  (becauseof  illegal  option +xyz). 

chatr  +b  enable  +xyz  enable  +mno  filel     file2  returns  8. 

For  PA64  chatr,  if  you  use  an  illegal  option,  chatr  returns  the  number  of  non-option  words  present 
after  the  first  illegal  option. 

chatr  +b  enable  +xyz  enable  +mno  enable  +pqr  enable  file  returns  4. 
I  nvalid  arguments 

If  you  use  an  invalid  argument  with  a  valid  option  and  you  do  not  specify  a  filename,  both  PA32  and  PA64 
chatr  return  0. 

chatr  +b  <noargument>  returns  0. 

For  PA32  chatr,  if  you  specify  a  file  name  (regardless  of  whether  or  not  the  file  exists),  chatr  returns 
number  of  words  in  the  command  line. 

chatr  +b    <no  argument>  file  returns  4. 

For  PA64  chatr,  if  you  specify  a  file  name  (regardless  of  whether  or  not  the  file  exists),  chatr  returns 
the  number  of  files  specified. 

chatr  +b  <noargument>  filel  file2  file3  returns  3. 
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Invalid  files 

For  both  PA32  and  PA64  chatr,  if  the  command  cannot  act  on  any  of  the  files  given,  it  returns  the  total 
number  of  files  specified  (if  some  option  is  specified).  Otherwise  it  returns  the  number  of  files  upon  which  it 
could  not  act. 

chatr  +b  enable  al  a2  a3  a4  (where  a2  does  not  have  read/write  permission)  returns  4. 
chatr  al  a2  a3  a4  returns  1. 

EXTERNAL  INFLUENCES 
Environment  Variables 

Thefollowing  internationalization  variables  affect  the  execution  of  chatr: 

LANG  Determines  the  locale  category  for  native  language,  local  customs  and  coded  character 

set  in  the  absence  of  LC_ALL  and  other  LC_*  environment  variables.  If  LANG  is  not 
specified  or  is  set  to  the  empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of 

LANG. 

LC_ALL  Determines  the  values  for  all  locale  categories  and  has  precedence  over  LANG  and  other 

LC_*  environment  variables. 

LC_CTYPE  Determines  the  locale  category  for  character  handlingfunctions. 

LC_ME S SAGE S     Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error. 

LC_NUMERIC      Determines  the  locale  category  for  numeric  formatting. 

NLSPATH  Determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

If  any  internationalization  variable  contains  an  invalid  setting,  chatr  behaves  as  if  all  internationaliza- 
tion variables  are  set  toe.  See  environ  (5). 

I  n  addition,  thefollowing  environment  variable  affects  chatr: 

TMPDIR  Specifies  a  directory  for  temporary  files  (seetmpnam(3S)). 

EXAMPLES 

Change  a.  out  to  demand-loaded 

chatr  -q  a. out 

Change  binding  mode  of  program  file  that  uses  shared  libraries  to  immediate  and  nonfatal.  Also  enable 
usage  of  SHLIB_PATH  environment  variable: 

chatr  -B  immediate  -B  nonfatal  +s  enable  a. out 

Disallow  run-time  path  lookup  for  the  shared  library  /usr/lib/libc .  si  that  the  shared  library 
libf  oo .  si  depends  on: 

chatr  +1  /usr/lib/libc . si  libf oo. si 

Given  segment  index  number  5  from  a  previous  run  of  chatr,  change  the  page  size  to  4  kilobytes: 
chatr  +si  5  +p  4K  average64 

AUTHOR 

chatr  was  developed  by  HP. 


SEE  ALSO 

System  Tools: 

ld(l) 
Miscellaneous: 

a. out (4) 

magic(4) 

sam(lM) 


invoke  the  link  editor 

assembler,  compiler,  and  linker  output 
magic  number  for  HP-UX  implementations 
system  administration  manager 
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Texts  and  Tutorials: 

HP-UX  Linker  and  Libraries  Online  User  Guide 

(Seethe+help  option) 
HP-UX  Linker  and  Libraries  User's  Guide 

(See  manuals(5)  for  ordering  information) 
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NAME 

checknr  -  check  nroff/troff  files 
SYNOPSIS 

checknr  [-s]  [-f]  [-a .  xl .  yl .  x2  .  y2  ...    .xn.yn]  [-c.xl.x2.x3...c  .xn]  [file  ...] 
DESCRIPTION 

checknr  searches  a  list  of  nrof  f  or  trof  f  input  files  for  certain  kinds  of  errors  involving  mismatched 
opening  and  closing  delimiters  and  unknown  commands.  If  no  files  are  specified,  checknr  searches  the 
standard  input,    checknr  looks  for  the  following: 

•  Font  changes  using \fx  ...  \fP. 

•  Size  changes  using \sx  ...  \s0. 

•  Macros  that  come  in  open  ...  close  forms,  such  as  the  .  TS  and  .  te  macros,  which  must  appear 
in  matched  pairs. 

checknr  knows  about  thems  and  me  macro  packages. 
Options 

checknr  recognizes  the  following  options: 

-a  Define  additional  macro  pairs  in  the  list,  -a  is  followed  by  groups  of  six  characters,  each 
group  defining  a  pair  of  macros.  Each  six  characters  consist  of  a  period,  the  first  macro  name, 
another  period,  and  the  second  macro  name.  For  example,  to  define  the  pairs  .BS  and  .ES, 
and  .  XS  and  .XE,  use: 

-a.BS .ES .XS .XE 

No  spaces  are  allowed  between  the  option  and  its  arguments, 
-c     Define  commands  that  checknr  would  otherwise  interpret  as  undefined, 
-f     I  gnore  \f  x  font  changes, 
-s     Ignore  \sx  size  changes. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Si  ngle-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

checknr  complains  about  unmatched  delimiters,  unrecognized  commands,  and  bad  command  syntax. 
EXAMPLES 

Check  file  sorting  for  errors  that  involve  mismatched  opening  and  closing  delimiters  and  unknown  com- 
mands, but  disregard  errors  caused  by  font  changes: 

checknr  -f  sorting 
WARNINGS 

checknr  is  designed  for  use  on  documents  prepared  with  the  intent  of  using  checknr,  much  the  same 
as  lint  is  used.  It  expects  a  certain  document  writing  style  for  \f...  and  \s...  commands,  in  which 
each  \fx  is  terminated  with  \fP  and  each  \sx  is  terminated  with  \s0.  Although  text  files  format  prop- 
erly when  the  next  font  or  point  size  is  coded  directly  instead  of  using  \fP  or  \s0,  such  techniques  pro- 
duce complaints  from  checknr.  If  files  are  to  be  examined  by  checknr,  the  \fP  and  \s0  delimiting  con- 
ventions should  be  used. 

-a  cannot  be  used  to  define  single-character  macro  names. 

checknr  does  not  recognize  certain  reasonable  constructs  such  as  conditionals. 

AUTHOR 

checknr  was  developed  by  the  University  of  California,  Berkeley. 

SEE  ALSO 

checkeq(l),  lint(l),  nroff(l). 
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NAME 

chfn  -  change  user  information;  used  by  finger 

SYNOPSIS 

chfn  [login-name] 

chfn  -r  files  [login-name] 

chfn  -r  nis  [login-name] 

chfn  -r  nisplus  [login-name] 

chfn  -r  dee  [login-name] 

DESCRIPTION 

The  chfn  command  changes  the  user  information  that  is  stored  in  the  repository  for  the  current 
logged-in  user  or  for  the  user  specified  by  login-name  (see  passwd(l)). 

The  information  is  organized  as  four  comma-separated  subfields  within  the  reserved  (5th)  field  of  the  pass- 
word file  entry.  It  consists  of  the  user's  full  name,  location  code,  office  phone  number,  and  home  phone 
number,  in  that  order.  This  information  is  used  by  the  finger  command  and  other  programs  (see 
finger(l)). 

chfn  prompts  you  for  each  subfield.  The  prompt  includes  a  default  value,  which  is  enclosed  in  brackets. 
Accept  the  default  value  by  pressing  the  Return  key.  To  enter  a  blank  subfield,  type  the  word  none. 

The  DCE  repository  (-r  dee)  is  only  availableif  I  ntegrated  Login  has  been  configured,  see  auth.adm(livi). 
If  Integrated  Login  has  been  configured,  other  considerations  apply.  A  user  with  appropriate  DCE 
privileges  is  capable  of  modifying  a  user's  finger  (gecos)  information;  this  is  not  dependent  upon  superuser 
privileges. 

If  the  repository  is  not  specified;  i.e.,  chfn  [login-name],  the  finger  information  is  changed  in  the  passwd 
file  only. 

Run  finger  after  running  chfn  to  make  sure  the  information  was  processed  correctly. 

Options 

Thefollowing  option  is  recognized: 

-r  Specify  the  repository  to  which  the  operation  is  to  be  applied.  Supported  repositories 

includefiles,  nis,  nisplus,  and  dee. 


Subfield  Values 

Name 


Location 
Office  Phone 

Home  Phone 


U  p  to  1022  pri  nti  ng  characters. 

The  finger  command  and  other  utilities  expand  an  &  found  anywhere  in  this 
subfield  by  substituting  the  login  name  for  it  and  shifting  the  first  letter  of  the 
login  name  to  uppercase,  (chfn  does  not  alter  the  input  &.) 

U  p  to  1022  pri  nti  ng  characters. 

U  p  to  25  pri  nti  ng  characters. 

finger  inserts  appropriate  hyphens  if  the  value  is  all  digits. 
U  p  to  25  pri  nti  ng  characters. 

finger  inserts  appropriate  hyphens  if  the  value  is  all  digits. 


Security  Restrictions 

You  must  have  appropriate  privileges  to  use  the  optional  login-name  argument  to  change  another  user's 
information. 


EXAMPLES 

Thefollowing  is  a  sample  run.  The  user's  input  is  shown  in  regular  type. 

Name    [Tracy  Simmons] : 

Location    (Ex:    47U-P5)    [] :  42L-P1 

Office  Phone    (Ex:    1632)    [77777] :  71863 

Home  Phone   (Ex:    9875432)    [4085551546] :  none 
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WARNINGS 

The  encoding  of  office  and  extension  information  is  installation-dependent. 

For  historical  reasons,  the  user's  name,  etc.,  are  stored  in  the  /etc/passwd  file.  This  is  an  inappropriate 
pi  ace  to  store  the  i  nformati  on. 

Because  two  users  may  try  to  write  the  passwd  file  at  once,  a  synchronization  method  was  developed.  On 
rare  occasions,  chfn  prints  a  message  that  the  password  file  is  busy.  When  this  occurs,  chfn  sleeps  for  a 
short  time,  then  tries  to  write  to  the  passwd  file  again. 

AUTHOR 

chfn  was  developed  by  the  University  of  California,  Berkeley. 

FILES 

/etc/passwd 
/etc/ptmp 

NOTES 

The  chfn  command  is  a  hard  link  to  passwd  command.  When  chfn  is  executed,  actually  the  passwd 
command  gets  executed  with  appropriate  arguments  to  change  the  user  gecos  information  in  the  repository 
specified  in  command  line.  If  no  repository  is  specified  the  gecos  information  is  changed  in  /etc/passwd 
file. 

SEE  ALSO 

chsh(l),  finger(l),  passwd(l),  passwd(4). 
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NAME 

chkey  -  change  user's  secure  RPC  key  pair 
SYNOPSIS 

chkey  [  -p  ]  [  -s    nisplus  |    nis  |    files  ] 
DESCRIPTION 

chkey  is  used  to  change  a  user's  secure  RPC  public  key  and  secret  key  pair,  chkey  prompts  for  the  old 
secure-rpc  password  and  verifies  that  it  is  correct  by  decrypting  the  secret  key.  If  the  user  has  not  already 
keylogged  in,  chkey  registers  the  secret  key  with  the  local  keyserv(lM)  daemon.  If  the  secure-rpc  pass- 
word does  not  match  the  login  password,  chkey  prompts  for  the  login  password,  chkey  uses  the  login 
password  to  encrypt  the  user's  secret  Diffie-Hellman  (192  bit)  cryptographic  key. 

chkey  ensures  that  the  login  password  and  the  secure-rpc  password  are  kept  the  same. 

The  key  pair  can  be  stored  in  the  /etc/publickey  file,  (see  publicke/(4)),  NIS  publickey  map  or 
NIS+  cred . org_dir  table.  If  a  new  secret  key  is  generated,  it  will  be  registered  with  the  local 
keyserv(lM)  daemon. 

If  the  source  of  the  publickey  is  not  specified  with  the  -s  option,  chkey  consults  the  publickey 
entry  in  the  name  service  switch  configuration  file  (see  nsswitch.conf(4)).  If  the  publickey  entry 
specifies  one  and  only  one  source,  then  chkey  will  change  the  key  in  the  specified  name  service.  However, 
if  multiple  name  services  are  listed,  chkey  can  not  decide  which  source  to  update  and  will  display  an  error 
message.  The  user  should  specify  the  source  explicitly  with  the  -s  option. 

Non  root  users  are  not  allowed  to  change  their  key  pair  in  the  /etc/publickey  file. 
Options 

-p  Re-encrypt  the  existing  secret  key  with  the  user's  login  password, 

-s  nisplus  U  pdate  the  N I S+ database, 
-s  nis         Update  the  NIS  database, 
-s  files      Update  the  files  database. 

AUTHOR 

chkey  was  developed  by  Sun  Microsystems,  I  nc. 

FILES 

/ etc/ nsswitch . conf 
/etc/publickey 

SEE  ALSO 

keylogin(l),  keylogout(l),  keyserv(lM),  newkey(lM),  nisaddcred(llM),  nsswitch. conf(4),  publickey(4). 
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NAME 

chmod  -  change  file  mode  access  permissions 
SYNOPSIS 

/usr/bin/chmod  [-A]  [-R]  symbol  icmodelist  file  ... 

Obsolescent  form: 

/usr/bin/chmod  [-A]  [-R]  numericmode  file  ... 

DESCRIPTION 

The  chmod  command  changes  the  permissions  of  one  or  more  files  according  to  the  value  of 
symbol  icmodelist  or  numeric  mode.  You  can  display  the  current  permissions  for  a  file  with  the  Is  -1 
command  (see  ls(l)). 

Symbolic  Mode  List 

A  symbol ic_mode_li st  is  a  comma-separated  list  of  operations  in  the  following  form.  Whitespace  is  not  per- 
mitted. 

[who]op[permission][, ...] 

The  vari  abl e  fiel ds  can  have  the  fol  I  owi  ng  val  ues: 

who  Oneor  more  of  the  fol  I  owing  letters: 

u     Modify  permissions  for  user  (owner), 
g     Modify  permissions  for  group, 
o     Modify  permissions  for  others. 

a     Modify  permissions  for  all  users  (a  is  equivalent  to  ugo). 

op  Required;  one  of  the  fol  I  owing  symbols: 

+     Add  permission  to  the  existing  file  mode  bits  of  who. 

Delete  permission  from  the  existing  file  mode  bits  of  who. 
=     Replace  the  existing  mode  bits  of  who  with  permission. 

permission  Oneor  more  of  the  fol  I  owing  letters: 

r     Add  or  delete  the  read  permission  for  who. 

w     Add  or  delete  the  write  permission  for  who. 

x     Add  or  delete  the  execute  file  (search  directory)  permission  for  who. 

s     Add  or  delete  the  set-owner-ID-on-file-execution  or  set-group-l D-on-file- 

execution  permission  for  who.  Useful  only  if  u  or  g  is  expressed  or  implied  in 

who. 

t     Add  or  delete  the  save-text-image-on-file-execution  (sticky  bit)  permission. 

Useful  only  if  u  isexpressed  or  implied  in  who.  Seechmod(2). 
X     Conditionally  add  or  delete  the  execute/search  permission  as  follows: 

•  If  file  is  a  directory,  add  or  delete  the  search  permission  to  the  existing  file 
mode  for  who.  (Same  as  x.) 

•  If  file  is  not  a  directory,  and  the  current  file  permissions  include  the  execute 
permission  (Is  -1  displays  an  x  or  an  s)  for  at  least  one  of  user,  group,  or 
other,  then  add  or  delete  the  execute  file  permission  for  who. 

•  If  file  is  not  a  directory,  and  no  execute  permissions  are  set  in  the  current 
file  mode,  then  do  not  change  any  execute  permission. 

Or  one  only  of  the  fol  I  owing  letters: 

u     Copy  the  current  user  permissions  to  who. 
g     Copy  the  current  group  permissions  to  who. 
o     Copy  the  current  other  permissions  to  who. 

The  operations  are  performed  in  the  order  specified,  and  can  override  preceding  operations  specified  in  the 
same  command  line. 

If  who  is  omitted,  the  r,  w,  x,  and  X  permissions  are  changed  for  all  users  if  the  changes  are  permitted  by 
the  current  file  mode  creation  mask  (see  umask(l)).  The  s  and  t  permissions  are  changed  as  if  a  was 
specified  in  who. 

Omitting  permission  is  useful  only  when  used  with  =  to  delete  all  permissions. 
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Numeric  Mode  (Obsolescent) 

Absolute  permissions  can  be  set  by  specifying  a  numericmode,  an  octal  number  constructed  from  the  logi- 
cal OR  (sum)  of  the  foil  owing  mode  bits: 

Miscellaneous  mode  bits: 


4000  (=u=s) 
2000  (=  g=s) 
1000     (=  u=t) 

Permission  mode  bits: 


0400 
0200 
0100 
0040 
0020 
0010 
0004 
0002 
0001 


(=  u=r) 
(=  u=w) 
(=  u=x) 
(=  g=r) 
(=  g=w) 
(=  g=x) 
(=  o=r) 
(=  o=w) 
(=  o=x) 


Set  user  ID  on  file  execution  (file  only) 
Set  group  ID  on  file  execution  (file  only) 
Set  sticky  bit;  see  below  and  chmod(2) 


Read  by  owner 
Write  by  owner 

Execute  (search  in  directory)  by  owner 

Read  by  group 

Write  by  group 

Execute/search  by  group 

Read  by  others 

Write  by  others 

Execute/search  by  others 


Options 

—A 


Preserve  any  optional  access  control  list  (ACL)  entries  associated  with  the  file  (HFS  file  systems 
only).  By  default,  in  conformance  with  the  IEEE  Standard  POSIX  1003.1-1988,  optional  HFS 
ACL  entries  are  deleted.  For  J  FS  ACLs,  this  option  has  no  effect,  because  optional  J  FS  ACL 
entries  are  always  preserved.  For  information  about  access  control  lists,  see  acl  (5)  and  aclv(5). 

-R  Recursively  change  the  file  mode  bits.  For  each  file  operand  that  names  a  directory,  chmod 
alters  the  file  mode  bits  of  the  named  directory  and  all  files  and  subdirectories  in  the  file  hierar- 
chy below  it. 

Only  the  owner  of  a  file,  or  a  user  with  appropriate  privileges,  can  change  its  mode. 

Only  a  user  having  appropriate  privileges  can  set  (or  retain,  if  previously  set)  the  sticky  bit  of  a  regular  file. 

If  the  sticky  bit  is  set  on  a  directory,  files  inside  the  directory  may  be  renamed  or  removed  only  by  the 
owner  of  the  file,  the  owner  of  the  directory,  or  the  superuser  (even  if  the  modes  of  the  directory  would  oth- 
erwise allow  such  an  operation). 

I  n  order  to  set  the  set-group-l  D  bit,  the  group  of  the  file  must  correspond  to  your  current  group  I D. 
If  chmod  is  used  on  a  symbolic  link,  the  mode  of  the  file  referred  to  by  the  link  is  changed. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

I f  LC_MES SAGES  is  not  specified  or  is  null,  it  defaults  to  the  value  of  LANG.  If  LANG  is  not  specified  or  is 
null,  it  defaults  toe  (see  lang(5)). 

If  any  internationalization  variable  contains  an  invalid  setting,  all  internationalization  variables  default  to 
C.  See  environ (5). 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

RETURN  VALUE 

Upon  completion,  chmod  returns  one  of  the  foil  owing  values: 

0    Successful  completion. 
>0    An  error  condition  occurred. 

EXAMPLES 

Deny  write  permission  to  others: 

chmod  o-w  file 
Make  a  file  executable  by  everybody: 
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chmod  a+x  file 

Assign  read  and  execute  permission  to  everybody,  and  set  the  set-user-l  D  bit: 

chmod  a=rx,u+s  file 
Assign  read  and  write  permission  to  the  file  owner,  and  read  permission  to  everybody  else: 

chmod  u=rw,go=r  file 
or  the  obsolescent  form: 

chmod  644  file 

Traverse  a  directory  subtree  making  all  regular  files  readable  by  user  and  group  only,  and  all  executables 
and  directories  executable  (searchable)  by  everyone: 

chmod  -R  ug+r,o-r,a+X  pathname 

If  the  current  value  of  umask  is  020  (umask  -S  displays  u=rwx,  g=rx,  o=rwx;  do  not  change  write 
permission  for  group)  and  the  current  permissions  for  filemytest  are  444  (a=r),  displayed  by  Is  -1  as 
-r — r — r — ,  then  the  command 

chmod  +w  mytest 

sets  the  permissions  to  646  (uo=rw,g=r),  displayed  by  Is  -1  as-rw-r — rw-. 

If  the  current  value  of  umask  is  020  (umask  -S  displays  u=rwx,  g=rx,  o=rwx;  do  not  change  write 
permission  for  group)  and  the  current  permissions  for  filemytest  are  666  (a=rw),  displayed  by  Is  -1  as 
-rw-rw-rw-,  then  the  command 

chmod  -w  mytest 

sets  the  permissions  to464  (uo=r,g=rw),  displayed  by  Is  -1  as-r — rw-r — . 

DEPENDENCIES 

The -A  option  causes  chmod  to  fail  on  file  systems  that  do  not  support  ACLs. 

AUTHOR 

chmod  was  developed  by  AT&T  and  HP. 

SEE  ALSO 

chacl(l),  ls(l),  umask(l),  chmod(2),  ad (5),  aclv(5). 

STANDARDS  CONFORMANCE 

chmod:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

chown,  chgrp  -  change  file  owner  or  group 

SYNOPSIS 

chown  [-h]  [-R]  owner[ : group]  file  ... 

chgrp  [-h]  [-R]  group  file  ... 
DESCRIPTION 

The  chown  command  changes  the  owner  I D  of  each  specified  file  to  owner  and  optionally  the  group  I D  of 
each  specified  fileto  group. 

The  chgrp  command  changes  the  group  ID  of  each  specified  fileto  group. 

owner  can  be  either  a  decimal  user  ID  or  a  login  name  found  in  the  /etc/passwd  file. 

group  can  be  either  a  decimal  group  ID  or  a  group  name  found  in  the  /etc/group  file. 

In  order  to  change  the  owner  or  group,  you  must  own  the  file  and  have  the  CHOWN  privilege  (see 
setprivgrp(lM)).  If  either  command  is  invoked  on  a  regular  file  by  other  than  the  superuser,  the  set-user- 
ID  and  set-group-ID  bits  of  the  file  mode  (04000  and  02000  respectively)  are  cleared.  Note  that  a  given 
user's  or  group's  ability  to  use  this  command  can  be  restricted  by  setprivgrp  (see  setprivgrp(lM)). 

Access  Control  Lists  -  HFS  File  Systems  Only 

Users  can  permit  or  deny  specific  individualsand  groups  to  access  a  file  by  setting  optional  ACL  entries  in 
the  file's  access  control  list  (see  acl(5)).  When  using  chown  in  conjunction  with  HFS  ACLs,  if  the  new 
owner  and/or  group  of  a  file  does  not  have  an  optional  ACL  entry  corresponding  to  user  .  %  and/or  % .  group 
in  the  file's  access  control  list,  the  file's  access  permission  bits  remain  unchanged.  However,  if  the  new 
owner  and/or  group  is  already  designated  by  an  optional  ACL  entry  of  user  .  %  and/or  %  .  group  in  the  file's 
ACL,  chown  sets  the  corresponding  file  access  permission  bits  (and  the  corresponding  baseACL  entries)  to 
the  permissions  contained  in  that  entry. 

Access  Control  Lists  -  J  FS  File  Systems  Only 

Users  can  permit  or  deny  specific  individualsand  groups  to  access  a  file  by  setting  optional  ACL  entries  in 
the  file's  access  control  list  (see  aclv(5)).  When  using  chown  in  conjunction  with  J  FS  ACLs,  if  the  new 
owner  and/or  group  of  a  file  have  optional  ACL  entries  corresponding  to  user :  uid :  perm  and/or 
group:  gid  :  perm  in  the  file's  access  control  list,  those  entries  remain  in  the  ACL  but  no  longer  have  any 
effect,  being  superseded  by  the  file's  user:  :  perm  and/or  group:  :  perm  entries. 

Options 

chown  and  chgrp  recognize  the  following  options: 

-h   Change  the  owner  or  group  of  a  symbolic  link. 

By  default,  the  owner  or  group  of  the  target  file  that  a  symbolic  link  points  to  is  changed.  With 
-h,  the  target  file  that  the  symbolic  link  points  to  is  not  affected.  If  the  target  file  is  a  directory, 
and  you  specify  -h  and  -R,  recursion  does  not  take  place. 

-R  Recursively  change  the  owner  or  group.  For  each  fileoperand  that  names  a  directory,  theowner 
or  group  of  the  directory  and  all  files  and  subdirectories  in  the  file  hierarchy  below  it  are 
changed. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  chown  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 
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RETURN  VALUE 

chown  and  chgrp  return  the  foil  owing  values: 

0    Successful  completion. 
>0    An  error  condition  occurred. 

EXAMPLES 

The  foil  owing  command  changes  the  owner  of  the  file  jokes  to  sandi: 
chown  sandi  jokes 

Thefollowing  command  searches  the  directory  design_notes  and  changes  each  file  in  that  directory  to 
owner  mark  and  group  users : 

chown  -R  mark: users  design_notes 
WARNINGS 

Thedefault  operation  of  chown  and  chgrp  for  symbolic  links  has  changed  as  of  HP-UX  release  10.0.  Use 
the  -h  option  to  get  the  former  default  operation. 

FILES 

/etc/group 
/etc/passwd 

SEE  ALSO 

chmod(l),  setprivgrp(lM),  chown(2),  group(4),  passwd(4),  acl(5),  aclv(5). 

STANDARDS  CONFORMANCE 

chown:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 

chgrp:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

chsh  -  change  default  login  shell 

SYNOPSIS 

chsh  login-name  [shell] 

chsh  -r  files  login-name  [shell] 
chsh  -r  nisplus  login-name  [shell] 
chsh  -r  nis  login-name  [shell] 
chsh  -r  dee  login-name  [shell] 

DESCRIPTION 

The  chsh  command  changes  the  login-shell  for  a  user's  login  name  in  the  repository  (see  passwd(l)). 

The  DCE  repository  (-r  dee)  is  only  availableif  I  ntegrated  Login  has  been  configured,  see  auth.adm(lM). 
If  Integrated  Login  has  been  configured,  other  considerations  apply.  A  user  with  appropriate  DCE 
privileges  iscapableof  modifying  a  user's  shell;  this  is  not  dependent  upon  superuser  privileges. 

If  the  repository  isnot  specified;  i.e.,  chsh  [login-name],  thelogin  shell  ischanged  in  pa  sswd  file  only. 

Run  finger  after  running  chsh  to  make  sure  the  information  was  processed  correctly. 

Arguments 

login-name  A  login  name  of  a  user. 

shell  The  absolute  path  name  of  a  shell.  If  the  file /etc/shells  exists,  the  new  login  shell 

must  be  listed  in  that  file.  Otherwise,  you  can  specify  one  of  the  standard  shells  listed  in 
the  getusershell  (3C)  manual  entry.  If  shell  is  omitted,  it  defaults  to  the  POSIX  shell, 
/usr/bin/ sh . 

Options 

Thefollowing  option  is  recognized: 

-r  Specify  the  repository  to  which  the  operation  is  to  be  applied.  Supported  repositories 

includefiles,  nis,  nisplus,  and  dee. 

Security  Restrictions 

You  must  have  the  syslog  sensitivity  label  to  execute  chsh .  You  must  have  the  owner  kernel  authori- 
zation to changeanother  user's  login  shell. 

NETWORKING  FEATURES 
NFS 

File /etc/passwd  can  be i mpl emented  asa  Network  Information  Service  (NIS)  database. 


EXAMPLES 

To  change  the  login  shell  for  user  voltaire  to  the  default: 

chsh  voltaire 
To  change  the  login  shell  for  user  descartes  to  the  C  shell: 

chsh  descartes  /usr/bin/csh 
To  change  the  login  shell  for  user  aristotle  totheKorn  shell  in  the  DCE  registry: 

chsh  -r  dee  aristotle  /usr/bin/ksh 

WARNINGS 

As  many  users  may  try  to  write  the  /etc/passwd  file  simultaneously,  a  passwd  locking  mechanism  was 
deviced.  If  this  locking  failsafter  subsequent  retrying,  chsh  terminates. 

AUTHOR 

ehsh  was  developed  by  HP  and  the  University  of  California,  Berkeley. 
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NOTES 

The  chsh  command  is  a  hard  link  to  passwd  command.  When  chsh  is  executed  actually  the  passwd 
command  gets  executed  with  appropriate  arguments  to  change  the  user  login  shell  in  the  repository 
specified  in  command  line.  If  no  repository  is  specified  the  login  shell  is  changed  in  /etc/passwd  file. 

FILES 

/etc/shells 
/etc/ptmp 

SEE  ALSO 

chfn(l),  csh(l),  ksh(l),  passwd(l),  sh(l),  sh-bourne(l),  sh-posix(l),  getusershell(3C),  pam(3),  passwd(4), 
shells(4). 
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NAME 

ci  -  check  in  RCS  revisions 

SYNOPSIS 

ci  [options]  file... 

DESCRIPTION 

ci  stores  new  revisions  into  RCS  files.  Each  file  name  ending  in  ,  v  is  treated  as  an  RCS  file;  all  others 
are  assumed  to  be  working  files,  ci  deposits  the  contents  of  each  working  file  into  the  corresponding  RCS 
file  (see  rcsintro(5)). 

If  the  RCS  file  does  not  exist,  ci  creates  it  and  deposits  the  contents  of  the  working  file  as  the  initial  revi- 
sion. The  default  number  is  "1.1".  The  access  list  is  initialized  to  empty.  I  nstead  of  the  log  message,  ci 
requests  descriptive  text  (seethe  -t  option  below). 

An  RCS  file  created  by  ci  inherits  the  read  and  execute  permissions  from  the  working  file.  If  the  RCS  file 
exists,  ci  preserves  its  read  and  execute  permissions,  ci  always  turns  off  all  write  permissions  of  RCS 
files. 

The  caller  of  the  command  must  have  read/write  permission  for  the  directories  containing  the  RCS  file  and 
the  working  file,  and  read  permission  for  the  RCS  file  itself.  A  number  of  temporary  files  are  created.  A 
semaphore  file  is  created  in  the  directory  containing  the  RCS  file,  ci  always  creates  a  new  RCS  file  and 
unlinks  the  old  one;  therefore  links  to  RCS  files  are  useless. 

For  ci  to  work,  the  user's  login  must  be  in  the  access  list  unless  the  access  list  is  empty,  the  user  is  the 
owner  of  the  file,  or  the  user  is  super-user. 

Normally,  ci  checks  whether  the  revision  to  be  deposited  is  different  from  the  preceding  one.  If  it  is  not 
different,  ci  either  aborts  the  deposit  (if  -q  is  given)  or  asks  whether  to  abort  (if  -q  is  omitted).  A  depo- 
sit can  be  forced  with  the  -f  option. 

If  sufficient  memory  is  not  availablefor  checking  the  difference  between  the  revision  to  be  deposited  and 
the  precedi ng  one,  then  either  swap  or  maxdsiz  values  can  be  increased. 

For  each  revision  deposited,  ci  prompts  for  a  log  message.  The  log  message  should  summarize  the  change 
and  must  be  terminated  with  a  line  containing  a  single "."  or  a  control-D.  If  several  files  are  being  checked 
in,  ci  asks  whether  or  not  to  reuse  the  log  message  from  the  previous  file.  If  the  standard  input  is  not  a 
terminal,  ci  suppresses  the  prompt  and  uses  the  same  log  message  for  all  files  (see  -m  option  below. 

The  number  of  the  deposited  revision  can  be  given  with  any  of  the  options  -r,  -f ,  -k,  -1,  -u,  or  -q  (see 
-r  option  below). 

To  add  a  new  revision  to  an  existing  branch,  the  head  revision  on  that  branch  must  be  locked  by  the  caller. 
Otherwise,  only  a  new  branch  can  be  created.  This  restriction  is  not  enforced  for  the  owner  of  the  file, 
unless  locking  is  set  to  strict  (see  rcs(l)).  A  lock  held  by  someone  else  can  be  broken  with  the  res 
command  (see  rcs(l)). 

Options 

-f  [rev]  Forces  a  deposit.  The  new  revision  is  deposited  even  if  it  is  not  different  from  the  preceding 

one. 

-k[rev]  Searches  the  working  file  for  keyword  values  to  determine  its  revision  number,  creation 

date,  author,  and  state  (see  co(l)),  and  assigns  these  values  to  the  deposited  revision, 
rather  than  computing  them  locally.  A  revision  number  given  with  a  command  option  over- 
rides the  number  in  the  working  file.  This  option  is  useful  for  software  distribution.  A  revi- 
sion that  is  sent  to  several  sites  should  be  checked  in  with  the  -k  option  at  these  sites  to 
preserve  its  original  number,  date,  author,  and  state. 

-l[rev]  Works  like-r,  except  it  performs  an  additional  co  -1  for  the  deposited  revision.  Thus, 

the  deposited  revision  is  immediately  checked  out  again  and  locked.  This  is  useful  for  sav- 
ing a  revision  although  one  wants  to  continue  editing  it  after  the  check-in. 

-m"msg"        Uses  the  string  msg  as  the  log  message  for  all  revisions  checked  in. 

-n"name"      Assigns  the  symbolic  name  name  to  the  checked-in  revision,    ci  prints  an  error  message 
if  name  is  already  assigned  to  another  number. 

-N"name"      Same  as  -n,  except  that  it  overrides  a  previous  assignment  of  name. 
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Quiet  mode;  diagnostic  output  is  not  printed.  A  revision  that  is  not  different  from  the 
preceding  one  is  not  deposited  unless  -f  is  given. 

Assignsthe  revision  number  rev  to  the  checked-i  n  revision,  releases  the  corresponding  lock, 
and  deletes  the  working  file.  This  is  the  default. 

If  rev  is  omitted,  ci  derives  the  new  revision  number  from  the  caller's  last  lock.  If  the 
caller  has  locked  the  head  revision  of  a  branch,  the  new  revision  is  added  to  the  head  of 
that  branch  and  a  new  revision  number  is  assigned  to  the  new  revision.  The  new  revision 
number  is  obtained  by  incrementing  the  head  revision  number.  If  the  caller  locked  a  non- 
head revision,  a  new  branch  is  started  at  the  locked  revision,  and  the  number  of  the  locked 
revision  is  incremented.  The  default  initial  branch  and  level  numbers  are  1.  If  the  caller 
holds  no  lock,  but  is  the  owner  of  the  file  and  locking  is  not  set  to  strict,  the  revision  is 
added  to  the  head  of  the  trunk. 

If  rev  indicates  a  revision  number,  it  must  be  higher  than  the  latest  one  on  the  branch  to 
which  rev  belongs,  or  must  start  a  new  branch. 

If  rev  indicates  a  branch  instead  of  a  revision,  the  new  revision  is  added  to  the  head  of  that 
branch.  The  level  number  is  obtained  by  incrementing  the  head  revision  number  of  that 
branch.  If  rev  indicates  a  non-existing  branch,  that  branch  is  created  with  the  initial  revi- 
sion numbered  rev.l. 

NOTE:  On  the  trunk,  revisions  can  be  added  to  the  head,  but  not  inserted. 

-s"state"       Sets  the  state  of  the  checked-i n  revision  to  the  identifier  state.  The  default  is  Exp. 

-t[txtfile]  Writes  descriptive  text  into  the  RCS  file  (deletes  the  existing  text).  If  txtfile  is  omitted,  ci 
prompts  the  user  for  text  from  standard  input  that  is  terminated  with  a  line  containing  a 
single  .  or  Ctrl-D.  Otherwise,  the  descriptive  text  is  copied  from  the  file  txtfile.  During 
initialization,  descriptive  text  is  requested  even  if  -t  is  not  given.  The  prompt  is 
suppressed  if  standard  input  is  not  a  terminal. 

-u[rev]  Similar  to  -1,  except  that  the  deposited  revision  is  not  locked.  This  is  useful  if  one  wants 

to  process  (e.g.,  compile)  the  revision  immediately  after  check  in. 

Access  Control  Lists  (acls) 

Optional  ACL  entries  should  not  be  added  to  RCS  files,  because  they  might  be  deleted. 

DIAGNOSTICS 

For  each  revision,  ci  prints  the  RCS  file,  the  working  file,  and  the  number  of  both  the  deposited  and  the 
preceding  revision.  The  exit  status  always  refers  to  the  last  file  checked  in,  and  is  0  if  the  operation  was 
successful,  1  if  unsuccessful. 

EXAMPLES 

If  the  current  directory  contains  a  subdirectory  RCS  with  an  RCS  file  io .  c,  v,  all  of  the  following  com- 
mands deposit  the  latest  revision  from  io.c  intoRCS/io.c,v: 

ci  io . c 

ci  RCS/io.c,v 

ci  io.c,v 

ci  io.c  RCS/io.c,v 

ci  io.c  io.c,v 

ci  RCS/io.c,v  io.c 

ci  io.c,v  io.c 

Check  in  version  1.2  of  RCS  file  f  oo .  c,  v,  with  the  message  Bug  fix: 

ci  -rl.2  -m"Bug  Fix"  foo.c,v 

WARNINGS 

The  names  of  RCS  files  are  generated  by  appending  ,  v  to  the  end  of  the  working  file  name.  If  the  result- 
ing RCS  file  name  is  too  long  for  the  file  system  on  which  the  RCS  file  should  reside,  ci  terminates  with 
an  error  message. 

The  log  message  cannot  exceed  2046  bytes. 

A  file  with  approximately  240  revisions  may  cause  a  hash  table  overflow,  ci  cannot  add  another  revision 
to  the  file  until  some  of  the  old  revisions  have  been  removed.  Use  the  res  -o  (obsolete)  command  option 


-q[  rev] 
-r[rev] 
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to  remove  old  revisions. 

RCS  is  designed  to  be  used  with  TEXT  files  only.  Attempting  to  use  RCS  with  non-text  (binary)  files  results 
in  data  corruption. 

AUTHOR 

ci  was  developed  by  Walter  F.  Tichy. 

SEE  ALSO 

co(l):  ident(l),  rcs(l),  rcsdiff(l),  rcsmerge(l),  rlog(l),  rcsfile(4):  acl(5),  rcsintro(5). 
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NAME 

ckconfig  -  verify  the  path  names  of  all  the  FTP  configuration  files. 

SYNOPSIS 

/usr/bin/ckconf ig 

DESCRIPTION 

The  ckconfig  utility  is  used  to  verify  the  path  names  of  the  FTP  configuration  files, 
/ etc/ f tpd/ f tpusers,  / etc/ f tpd/ f tpaccess,  / etc/ f tpd/ f tpconversions, 

/etc/ftpd/ftpgroups,  /etc/ftpd/ftphosts,  /var/adm/syslog/xferlog,  and 
/etc/ftpd/pids/*. 

This  utility  checks  to  see  that  all  the  FTP  configuration  files  are  in  the  path  specified.  If  it  is  not  able  to  find 
the  configuration  files  in  the  path,  it  will  give  out  an  error  message  to  the  system  administrator  about  the 
same. 

FILES 

/usr/bin/ckconf ig 

AUTHOR 

ckconfig  was  developed  by  the  Washington  University,  St.  Louis,  Missouri. 
SEE  ALSO 

ftpusers(4),  ftpconversions(4),  ftpaccess(4),  ftphosts(4),  ftpgroups(4),  xferlog(5). 
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NAME 

cksum  -  print  file  checksum  and  sizes 

SYNOPSIS 

cksum  [file  ...] 

DESCRIPTION 

The  cksum  command  calculates  and  prints  to  standard  output  a  checksum  for  each  named  file,  the  number 
of  octets  in  thefileand  the  filename. 

cksum  uses  a  portable  algorithm  based  on  a  32-bit  Cyclic  Redundancy  Check.  This  algorithm  finds  a 
broader  spectrum  of  errors  than  the  16-bit  algorithms  used  by  sum  (see  sum(l)).  The  CRC  is  the  sum  of 
the  foil  owing  expressions,  where  x  is  each  byte  of  the  file. 

x32  +x26  +x23  +x22  +x16  +x12  +X11  +x10  +x7  +x5  +x4  +x2  +X1  +x° 

The  results  of  the  calculation  are  truncated  to  a  32-bit  value.  The  number  of  bytes  in  the  file  is  also 
printed. 

Standard  input  isused  if  no  file  names  are  given. 

cksum  is  typically  used  to  verify  data  integrity  when  copying  files  between  systems. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  set  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used. 

LC_CTYPE  determines  the  locale  for  interpretation  of  sequences  of  bytes  of  text  data  as  characters  (e.g., 
single-  verses  multibyte characters  in  arguments  and  input  files). 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  any  internationalization  variable  contains  an  invalid  setting,  cksum  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

RETURN  VALUE 

Upon  completion,  cksum  returns  one  of  the  foil  owing  values: 

0   All  files  were  processed  successfully. 

>0    One  or  more  files  could  not  be  read  or  another  error  occurred. 

If  an  inaccessible  file  is  encountered,  cksum  continues  processing  any  remaining  files,  but  the  final  exit 
status  is  affected. 

SEE  ALSO 

sum(l),  wc(l),  pdf(4). 

STANDARDS  CONFORMANCE 

cksum:  XPG4,  POSIX.2 
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NAME 

clear  -  clear  terminal  screen 

SYNOPSIS 

clear 

DESCRIPTION 

clear  clears  the  terminal  screen  if  it  is  possible  to  do  so.  It  reads  the  TERM  environment  variablefor  the 
terminal  type,  then  reads  the  appropriate  terminfo  database  to  determine  how  to  clear  the  screen. 

FILES 

/usr/share/lib/terminf o/?/*    terminal  databasefiles 
AUTHOR 

clear  was  developed  by  the  University  of  California,  Berkeley. 

SEE  ALSO 

terminfo(4). 
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NAME 

cmp  -  compare  two  files 

SYNOPSIS 

cmp  [-1]  [-s]  filel  file2  [skipl  [skip2]] 

DESCRIPTION 

cmp  compares  two  files  (if  filel  or  file2  is  -,  the  standard  input  is  used).  Under  default  options,  cmp 
makes  no  comment  if  the  files  are  the  same;  if  they  differ,  it  announces  the  byte  and  line  number  at  which 
the  difference  occurred.  If  one  file  is  an  initial  subsequence  of  the  other,  that  fact  is  noted,  skipl  and  skip2 
are  initial  byte  offsets  into  filel  and  file2,  respectively;  and  maybe  octal  or  decimal;  the  form  of  the  number 
is  determined  by  the  environment  variable  LC_NUMERIC  (in  the  C  locale,  a  leading  0  denotes  an  octal 
number.  See  LANG  on  environ (5)  and  strtol  (3C)). 

cmp  recognizes  the  following  options: 

-1       Print  the  byte  number  (decimal)  and  the  differing  bytes  (octal)  for  each  difference  (byte 
numbering  begins  at  1  rather  than  0). 

-s       Print  nothing  for  differing  files;  return  codes  only. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable 
contains  an  invalid  setting,  cmp  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

cmp  returns  the  following  exit  values: 

0  Files  are  identical. 

1  Files  are  not  identical. 

2  I  naccessibleor  missing  argument. 

cmp  prints  the  foil  owing  warning  if  the  comparison  succeeds  till  the  end  of  file  of  filel(file2)  is  reached, 
cmp:   EOF  on  filel (file2) 

SEE  ALSO 

comm(l),  diff(l). 

STANDARDS  CONFORMANCE 

cmp:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

co  -  check  out  RCS  revisions 

SYNOPSIS 

co  [options]  file  ... 

DESCRIPTION 

co  retrieves  revisions  from  RCS  files.  Each  file  name  ending  in  ,  v  is  taken  to  be  an  RCS  file.  All  other 
files  are  assumed  to  be  working  files,  co  retrieves  a  revision  from  each  RCS  file  and  stores  it  in  the 
corresponding  working  file  (see  also  rcsintro(5)). 

Revisions  of  an  RCS  file  can  be  checked  out  locked  or  unlocked.  Locking  a  revision  prevents  overlapping 
updates.  A  revision  checked  out  for  reading  or  processing  (e.g.,  compiling)  need  not  be  locked.  A  revision 
checked  out  for  editing  and  later  checked  in  must  normally  be  locked.  Locking  a  revision  currently  locked 
by  another  user  fails  (a  lock  can  be  broken  with  the  res  command,  but  poses  inherent  risks  when  indepen- 
dent changes  are  being  made  simultaneously  (see  rcs(l)).  co  with  locking  requires  the  caller  to  be  on  the 
access  list  of  the  RCS  file  unless:  he  is  the  owner  of  the  file,  a  user  with  appropriate  privileges,  or  the  access 
list  is  empty,    co  without  locking  is  not  subject  to  access  list  restrictions. 

A  revision  is  selected  by  number,  check-in  date/time,  author,  or  state.  If  none  of  these  options  are 
specified,  the  latest  revision  on  the  trunk  is  retrieved.  When  the  options  are  applied  in  combination,  the 
latest  revision  that  satisfies  all  of  them  is  retrieved.  The  options  for  date/time,  author,  and  state  retrieve  a 
revision  on  the  selected  branch.  The  selected  branch  is  either  derived  from  the  revision  number  (if  given), 
or  is  the  highest  branch  on  the  trunk.  A  revision  number  can  be  attached  to  the  options  -1,  -p,  -q,  or  -r. 

The  caller  of  the  command  must  have  write  permission  in  the  working  directory,  read  permission  for  the 
RCS  file,  and  either  read  permission  (for  reading)  or  read/write  permission  (for  locking)  in  the  directory  that 
contains  the  RCS  file. 

The  working  file  inherits  the  read  and  execute  permissions  from  the  RCS  file.  I  n  addition,  the  owner  write 
permission  is  turned  on,  unless  the  file  is  checked  out  unlocked  and  locking  is  set  to  strict  (seercs(l)). 

If  a  file  with  the  name  of  the  working  file  exists  already  and  has  write  permission,  co  aborts  the  check  out 
if  -q  is  given,  or  asks  whether  to  abort  if  -q  is  not  given.  If  the  existing  working  file  is  not  writable,  it  is 
deleted  before  the  check  out. 

A  number  of  temporary  files  are  created.  A  semaphore  file  is  created  in  the  directory  of  the  RCS  file  to 
prevent  simultaneous  update. 

A  co  command  applied  to  an  RCS  file  with  no  revisions  creates  a  zero-length  file,  co  always  performs 
keyword  substitution  (see  below). 

Options 

-l[rev]  Locks  the  checked  out  revision  for  the  caller.  If  omitted,  the  checked  out  revision  is  not 

locked.  Seeoption  -r  for  handlingof  the  revision  number  rev. 

-p[rev]  Prints  the  retrieved  revision  on  the  standard  output  rather  than  storing  it  in  the  working 

file.  This  option  is  useful  when  co  is  part  of  a  pipe. 

-q[rev]  Quiet  mode;  diagnostics  are  not  printed. 

-ddate  Retrieves  the  latest  revision  on  the  selected  branch  whose  check  in  date/time  is  less  than  or 

equal  to  date.  The  date  and  time  may  be  given  in  free  format  and  are  converted  to  local 
time.  Examples  of  formats  for  date: 

Tue-PDT,  1981,  4pm  Jul  21  (free format) 

Fri  April  16  15:52:25  EST  1982      (output  Of  Cti me(3C)) 

4/21/86  10:30am  (format:  mm/dd/yy  hh : mm : ss) 

Most  fields  in  the  date  and  time  can  be  defaulted,  co  determines  the  defaults  in  the  order 
year,  month,  day,  hour,  minute,  and  second  (from  most-  to  least-significant).  At  least  one 
of  these  fields  must  be  provided.  For  omitted  fields  that  are  of  higher  significance  than  the 
highest  provided  field,  the  current  values  are  assumed.  For  all  other  omitted  fields,  the 
lowest  possible  values  are  assumed.  For  example,  the  date  20,  10:30  defaults  to 
10:30:00  of  the  20th  of  the  current  month  and  current  year.  Date/time  fields  can  be  delim- 
ited by  spaces  or  commas.  If  spaces  are  used,  the  string  must  be  surrounded  by  double 
quotes. 
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For  2-digit  year  input  (yy)  without  the  presence  of  the  century  field,  the  following  interpre- 
tation istaken:  [70-99,  00-69  (1970-1999,2000-2069)]. 

-r[rev]  Retrieves  the  latest  revision  whose  number  is  less  than  or  equal  to  rev.  If  rev  indicates  a 

branch  rather  than  a  revision,  the  latest  revision  on  that  branch  is  retrieved,  rev  is  com- 
posed of  one  or  more  numeric  or  symbolic  fields  separated  by  .  .  The  numeric  equivalent  of 
a  symbolicfield  isspecified  with  the  ci  -n  and  res  -n  commands  (see ci (1)  and  rcs(l)). 

-sstate  Retrieves  the  latest  revision  on  the  selected  branch  whose  state  is  set  to  state. 

-w[login]  Retrieves  the  latest  revision  on  the  selected  branch  that  was  checked  in  by  the  user  with 
login  name  login.  If  the  argument  login  is  omitted,  the  caller's  login  is  assumed. 

-jjoinlist  Generates  a  new  revision  that  is  the  result  of  the  joining  of  the  revisions  on  joinlist.  join- 
list  is  a  comma-separated  list  of  pairs  of  the  form  rev2 :  rev3,  where  rev2  and  rev3  are  (sym- 
bolic or  numeric)  revision  numbers.  For  the  initial  pair,  revl  denotes  the  revision  selected 
by  the  options -1,  -w.  For  all  other  pairs,  revl  denotes  the  revision  generated  by  the 
previous  pair.  (Thus,  the  output  of  one  join  becomes  the  input  to  the  next.) 

For  each  pair,  co  joins  revisions  revl  and  rev3  with  respect  to  rev2.  This  means  that  all 
changes  that  transform  rev2  into  revl  are  applied  to  a  copy  of  rev3.  This  is  particularly 
useful  if  revl  and  rev3  are  the  ends  of  two  branches  that  have  rev2  as  a  common  ancestor. 
If  revl  <  rev2  <  rev3  on  the  same  branch,  joining  generates  a  new  revision  that  is  similar 
to  rev3,  but  with  all  changes  that  lead  from  revl  to  rev2  undone.  If  changes  from  rev2  to 
revl  overlap  with  changes  from  rev2  to  rev3,  co  prints  a  warning  and  includes  the  overlap- 
ping sections,  delimited  as  follows: 

«««< 
revl 


rev3 

»»»> 


For  the  initial  pair,  rev2  can  be  omitted.  The  default  is  the  common  ancestor.  If  any  of  the 
arguments  indicate  branches,  the  latest  revisions  on  those  branches  are  assumed.  If  the 
-1  option  is  present,  the  initial  revl  is  locked. 

Keyword  Substitution 

Strings  of  the  form  $keyword$  and  $keyword  :  ...$  embedded  in  the  text  are  replaced  with  strings  of  the 
form  $keyword  :  value  $,  where  keyword  and  valueare  pairs  listed  below.  Keywords  may  be  embedded  in 
literal  strings  or  comments  to  identify  a  revision. 

Initially,  the  user  enters  strings  of  the  form  $keyword$.  On  check  out,  co  replaces  these  strings  with 
strings  of  the  form  $keyword  :  value  $.  If  a  revision  containing  strings  of  the  latter  form  is  checked  back 
in,  the  value  fields  are  replaced  during  the  next  checkout.  Thus,  the  keyword  values  are  automatically 
updated  on  checkout. 

Keywords  and  their  corresponding  values: 

$Author$      The  login  name  of  the  user  who  checked  in  the  revision. 
$Date$         The  date  and  time  the  revision  was  checked  in. 

$Header$      A  standard  header  containing  the  RCS  file  name,  the  revision  number,  the  date,  the  author, 
and  the  state. 

$Locker$      The  login  name  of  the  user  who  locked  the  revision  (empty  if  not  locked). 

$Log$  The  log  message  supplied  during  checkin,  preceded  by  a  header  containing  the  RCS  file 

name,  the  revision  number,  the  author,  and  the  date.  Existing  log  messages  are  not 
replaced.  Instead,  the  new  log  message  is  inserted  after  $Log:  ...$.  This  is  useful  for 
accumulating  a  complete  change  log  in  a  source  file. 

$Revision$  The  revision  number  assigned  to  the  revision. 

$Source$      The  full  pathname  of  the  RCS  file. 

$State$       The  state  assigned  to  the  revision  with  res  -s  or  ci  -s. 
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Access  Control  Lists  (ACLs) 

Optional  ACL  entries  should  not  be  added  toRCS  files  because  they  might  be  deleted. 

DIAGNOSTICS 

The RCS  file  name,  the  working  file  name,  and  the  revision  number  retrieved  are  written  to  the  diagnostic 
output.  The  exit  status  always  refers  to  the  last  file  checked  out,  and  is  0  if  the  operation  was  successful,  1 
if  unsuccessful. 

EXAMPLES 

Assume  the  current  directory  containsa  subdirectory  named  RCS  with  an  RCS  file  named  io.c,v.  Each 
of  the  foil  owing  commands  retrieves  the  latest  revision  from  RCS/io.c,  v  and  stores  it  into  io .  c: 

co  io.c 

co  RCS/io.c, v 

co  io.c,v 

co  io.c     RCS/io.c,  v 

co  io.c  io.c,v 

co  RCS/io.c,  v  io.c 

co  io.c,v  io.c 

Check  out  version  1.1  of  RCS  file  f  oo .  c,  v: 

co  -rl.l  foo.c,v 
Check  out  version  1.1  of  RCS  file  foo.c,v  to  the  standard  output: 

co  -pl.l  foo.c,v 
Check  out  the  version  of  file  foo .  c,  v  that  existed  on  September  18,  1992: 

co  -d"09/18/92"  foo.c,v 

WARNINGS 

The  co  command  generates  the  working  file  name  by  removing  the  ,  v  from  the  end  of  the  RCS  file  name. 
If  the  given  RCS  file  name  is  too  long  for  the  file  system  on  which  the  RCS  file  should  reside,  co  terminates 
with  an  error  message. 

There  is  no  way  to  suppress  the  expansion  of  keywords,  except  by  writing  them  differently.  In  nroff  and 
troff,  this  is  done  by  embedding  the  null-character  \&  i nto  the  keyword. 

The  -d  option  gets  confused  in  some  circumstances,  and  accepts  no  date  before  1970. 

The  -j  option  does  not  work  for  files  containing  lines  consisting  of  a  single  .  . 

RCS  is  designed  to  be  used  with  text  files  only.  Attempting  to  use  RCS  with  non-text  (binary)  files  results  in 
data  corruption. 

AUTHOR 

co  was  developed  by  Walter  F.  Tichy. 

SEE  ALSO 

ci(l),  ident(l),  rcs(l),  rcsdiff(l),  rcsmerge(l),  rlog(l),  rcsfile(4),  ad (5),  rcsintro(5). 
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NAME 

col  -  filter  reverse  line-feeds  and  backspaces 

SYNOPSIS 

col  [-blfxp] 

DESCRIPTION 

col  reads  from  the  standard  input  and  writes  onto  the  standard  output.  It  performs  the  line  overlays 
implied  by  reverse  line  feeds  (ASCII  code  esc-7),  and  by  forward  and  reverse  half-linefeeds  (esc-9  and 
esc-8).  col  is  particularly  useful  for  filtering  multi-column  output  made  with  the  nroff  .rt  com- 
mand, and  output  resulting  from  use  of  the  tbl  preprocessor  (see  nroff(l)  and  tbl  (1)). 

Ifthe  -b  option  is  given,  col  assumes  that  the  output  device  in  use  is  not  capableof  backspacing.  Inthis 
case,  if  two  or  more  characters  are  to  appear  in  the  same  place,  only  the  last  one  read  is  output. 

Ifthe  -1  option  is  given,  col  assumes  the  output  device  is  a  line  printer  (rather  than  a  character  printer) 
and  removes  backspaces  in  favor  of  multiply  overstruck  full  lines.  It  generates  the  minimum  number  of 
print  operations  necessary  to  generate  the  required  number  of  overstrikes.  (All  but  the  last  print  operation 
on  a  line  are  separated  by  carriage  returns  (\  r);  the  last  print  operation  is  terminated  by  a  newline  (\  n).) 

Although  col  accepts  half-line  motions  in  its  input,  it  normally  does  not  emit  them  on  output.  Instead, 
text  that  would  appear  between  lines  is  moved  to  the  next  lower  full-line  boundary.  This  treatment  can  be 
suppressed  by  the  -f  (fine)  option;  in  this  case,  the  output  from  col  may  contain  forward  half-linefeeds 
(ESC-9),  but  will  still  never  contain  either  kind  of  reverse  line  motion. 

Unless  the  -x  option  is  given,  col  converts  white  space  to  tabs  on  output  wherever  possible  to  shorten 
printing  time. 

The  ASCI  I  control  characters  SO  (\  016)  and  Si  (\  017)  are  assumed  by  col  to  start  and  end  text  in  an  alter- 
nate character  set.  The  character  set  to  which  each  input  character  belongs  is  remembered,  and  on  output 
Si  and  SO  characters  are  generated  as  appropriate  to  ensure  that  each  character  is  printed  in  the  correct 
character  set. 

On  input,  the  only  control  characters  accepted  are  space,  backspace,  tab,  return,  new-line,  Si  ,  SO  ,  and  vt  , 
(\013),  and  ESC  followed  by  7,  8,  or  9.  The  vt  character  is  an  alternate  form  of  full  reverse  line-feed, 
included  for  compatibility  with  some  earlier  programs  of  this  type.  All  other  non-printing  characters  are 
ignored. 

Normally,  col  ignores  any  unrecognized  escape  sequences  found  in  its  input;  the  -p  option  can  be  used 
to  cause  col  to  output  these  sequences  as  regular  characters,  subject  to  overprinting  from  reverse  line 
motions.  The  use  of  this  option  is  highly  discouraged  unless  the  user  isfully  aware  of  the  textual  position  of 
the  escape  sequences. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  col  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

col  is  used  most  often  with  nroff  and  tbl.  A  common  usage  is: 
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tbl  filename  |  nroff  -man   |   col   |  more  -s 

(very  similar  to  the  usual  man(l)  command).  This  command  allows  vertical  bars  and  outer  boxes  to  be 
printed  for  tables.  The  file  is  run  through  the  tbl  preprocessor,  and  the  output  is  then  piped  through 
nroff,  formatting  the  output  using  the  -man  macros.  Theformatted  output  isthen  piped  through  col, 
which  sets  up  the  vertical  bars  and  aligns  the  columns  in  the  file.  The  file  is  finally  piped  through  the 
more  command,  which  prints  the  output  to  the  screen  with  underlining  and  highlighting  substituted  for 
italic  and  bold  typefaces.  The  -s  option  deletes  excess  space  from  the  output  so  that  multiple  blank  lines 
are  not  printed  to  the  screen. 

SEE  ALSO 

nroff(l),  tbl(l),  ul(l),  man(5). 

NOTES 

The  input  format  accepted  by  col  matches  the  output  produced  by  nroff  with  either  the  -T37  or  - 
Tip  options.  Use  -T37  (and  the  -f  option  of  col)  if  the  ultimate  disposition  of  the  output  of  col  is  a 
device  that  can  interpret  half-line  motions,  and  -Tip  otherwise. 

BUGS 

Cannot  back  up  more  than  128  lines.  Cannot  back  up  across  page  boundaries. 

There  is  a  maximum  limit  for  the  number  of  characters,  including  backspaces  and  overstrikes,  on  a  line. 
The  maximum  limit  is  at  least  800  characters. 

Local  vertical  motions  that  would  result  in  backing  up  over  the  first  line  of  the  document  are  ignored.  As  a 
result,  the  first  line  must  not  haveany  superscripts. 


This  command  is  likely  to  be  withdrawn  from  X/Open  standards.  Applications  using  this  command  might 
not  be  portable  to  other  vendors'  systems. 

STANDARDS  CONFORMANCE 

col:  SVI D2,  SVI D3,  XPG2,  XPG3 


WARNINGS 
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NAME 

comb  -  combine  sees  deltas 

SYNOPSIS 

comb  [-pSlD]  [-clist]  [-o]  [-s]  file  ... 

DESCRIPTION 

The  comb  command  generates  a  shell  procedure  (see  sh(l))  which,  when  run,  reconstructs  the  given  sees 
files.  The  reconstructed  files  are  usually  smaller  than  the  original  files.  Arguments  can  be  specified  in  any 
order,  but  all  options  apply  to  all  named  sees  files.  If  a  directory  is  named,  comb  behaves  as  though  each 
file  in  the  directory  were  specified  as  a  named  file,  except  that  non-SCCS  files  (last  component  of  the  path 
name  does  not  begin  with  s  . )  and  unreadable  files  are  silently  ignored.  If  a  name  of  -  is  given,  the  stan- 
dard input  is  read;  each  line  of  the  standard  input  is  taken  to  be  the  name  of  an  sees  file  to  be  processed; 
non-SCCS  files  and  unreadable  files  are  silently  ignored.  The  generated  shell  procedure  is  written  on  the 
standard  output. 

Options 

comb  recognizes  the  following  options.  Each  is  explained  as  if  only  one  named  file  is  to  be  processed,  but 
the  effects  of  any  option  apply  independently  to  each  named  file. 

-pSlD  The  Sees  I  Dentification  string  (SID)  of  the  oldest  delta  to  be  preserved.  All  older  del- 

tas are  discarded  in  the  reconstructed  file. 

-clist  A  list  of  deltas  to  be  preserved  (see  get(l)  for  the  syntax  of  a  list).  All  other  deltas  are 

discarded. 

-o  For  each  get  -e  generated,  this  option  causes  the  reconstructed  file  to  be  accessed 

at  the  release  of  the  delta  to  be  created,  otherwise  the  reconstructed  file  would  be 
accessed  at  the  most  recent  ancestor.  Use  of  the  -o  option  can  decrease  the  size  of 
the  reconstructed  sees  file.  It  can  also  alter  the  shape  of  the  delta  tree  of  the  original 
file. 

-s  This  option  causes  comb  to  generate  a  shell  procedure  which,  when  run,  produces  a 

report  giving,  for  each  file:  the  file  name,  size  (in  blocks)  after  combining,  original  size 
(also  in  blocks),  and  percentage  change  computed  by: 

100 x  (original  -  combined)  /  original 

It  is  recommended  that  this  option  be  used  before  any  sees  files  are  actually  com- 
bined to  determine  exactly  how  much  space  is  saved  by  the  combining  process. 

If  no  options  are  specified,  comb  preserves  only  leaf  deltas  and  the  minimal  number  of  ancestors  needed  to 
preserve  the  tree. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Usesccshelp(l)  for  explanations. 

EXAMPLES 

The  command: 

comb  -cl .1,1.3,1.6  s. document   >  save_f ile 

creates  a  shell  script  named  save_file,  which  if  executed,  creates  a  new  s  .document  using  only  the 
deltas  1.1,  1.3, and  1.6  from  the  old  s. document.  The  script  overwrites  the  old  s. document; 
thus,  it  might  be  wise  to  copy  the  original  elsewhere.  Here  is  an  example  of  typical  technique: 

cp  s . document  s . save 

comb  -cl .1,1.3,1.6  s. document   >  save_f ile 
sh  save_file 

WARNINGS 

comb  may  rearrange  the  shape  of  the  tree  of  deltas.  Combining  files  may  or  may  not  save  space;  in  fact,  it 
is  possible  for  the  reconstructed  file  to  actually  be  larger  than  the  original. 
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FILES 

s.COMB?????  Temporary  file 

comb?????  Temporary  file 

SEE  ALSO 

admin(l),  delta(l),  get(l),  sccshelp(l),  prs(l),  sh(l),  sccsfile(4). 
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NAME 

comm  -  select  or  reject  lines  common  to  two  sorted  files 

SYNOPSIS 

comm  [-[123]]  filel  file2 

DESCRIPTION 

comm  reads  filel  and  file2,  which  should  be  ordered  in  increasing  collating  sequence  (see  sort(l)  and 
Environment  Variables  below),  and  produces  a  three-column  output: 

Column  1:  Lines  that  appear  only  in  filel, 
Column  2:  Lines  that  appear  only  in  file2, 
Column  3:    Lines  that  appear  in  both  files. 

If  -  is  used  for  filel  or  file2,  the  standard  input  is  used. 

Options  1,  2,  or  3  suppress  printing  of  the  corresponding  column.  Thus  comm  -12  prints  only  the  lines 
common  to  the  two  files;  comm  -23  prints  only  lines  in  the  first  file  but  not  in  the  second;  comm  -123 
does  nothing  useful. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  comm  expects  from  the  input  files. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG 
determines  the  language  in  which  messages  are  displayed.  If  LC_COLLATE  is  not  specified  in  the 
environment  or  is  set  to  the  empty  string,  the  valueof  LANG  is  used  as  a  default.  If  LANG  is  not  specified 
or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationaliza- 
tion variable  contains  an  invalid  setting,  comm  behaves  as  if  all  internationalization  variables  are  set  to 
"C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

The  following  examples  assume  that  filel  and  file2  have  been  ordered  in  the  collating  sequence 
defined  by  the  LC_COLLATE  or  LANG  environment  variable. 

Print  all  lines  common  to  filel  and  file2  (i  n  other  words,  print  column  3): 

comm  -12  filel  file2 
Print  all  lines  that  appear  in  filel  but  not  in  file2  (in  other  words,  print  column  1): 

comm  -23  filel  file2 
Print  all  lines  that  appear  in  file2  but  not  in  filel  (in  other  words,  print  column  2): 

comm  -13  filel  file2 

SEE  ALSO 

cmp(l),  diff(l),  sdiff(l),  sort(l),  uniq(l). 

STANDARDS  CONFORMANCE 

comm:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

command  -  execute  a  simple  command 

SYNOPSIS 

command  commandname  [argument  ...] 

DESCRIPTION 

command  enables  the  shell  to  treat  the  arguments  as  a  simple  command,  suppressing  the  shell  function 
lookup. 

If  command  name  is  not  the  name  of  the  function,  the  effect  of  command  is  the  same  as  omitting  com- 
mand. 

OPERANDS 

command  recognizes  the  following  operands: 

command  name      Thenameof  a  HP-UX  command  or  a  shell  built-in  command. 

argument  One  or  more  stri  ngs  to  be  i  nterpreted  as  arguments  to  command  name. 

The  command  command  is  necessary  to  allow  functions  that  have  the  same  name  as  a  command  to  call 
the  command  (instead  of  a  recursive  call  to  the  function). 

Nothing  in  the  description  of  command  is  intended  to  imply  that  the  command  line  is  parsed  any 
differently  than  any  other  simple  command.  For  example, 

command  a  |  b  ;  c 

is  not  parsed  in  any  special  way  that  causes  |  or  ;  to  be  treated  other  than  a  pipe  operator  or  semicolon 
or  that  prevents  function  lookup  on  b  or  c. 

EXTERNAL  INFLUENCE 
Environment  Variables 

PATH  determines  the  search  path  used  during  the  command  search. 

RETURN  VALUE 

command  exits  with  one  of  the  foil  owing  values: 

•  If  command  fails: 

126  The  utility  specified  by  the  command  name  is  found  but  not  executable. 

127  An  error  occurred  in  the  command  utility  or  the  utility  specified  by  command  name 
is  not  found. 

•  If  command  does  not  fail: 

The  exit  status  of  command  is  the  same  as  that  of  the  simple  command  specified  by  the 
arguments: 

command  name!  argument  ■■■] 

EXAMPLES 

Create  a  version  of  the  cd  command  that  always  prints  the  name  of  the  new  working  directory  whenever 
it  is  used: 

cd()  { 

command  "$@"  >/dev/null 
pwd 

} 

Circumvent  the  redefined  cd  command  above,  and  change  directories  without  printing  the  name  of  the 
new  working  directory: 

command  cd 

SEE  ALSO 

getconf(l),  sh-posix(l),  confstr(3C). 
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STANDARDS  CONFORMANCE 

command:  XPG4,  P0SIX.2 
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NAME 

compact,  uncompact,  ccat  -  compact  and  uncompact  files,  and  cat  them 

SYNOPSIS 

compact  [name  ...] 

uncompact  [name  ...] 
ccat  [file  ...] 

DESCRIPTION 

compact  compresses  the  named  files  using  an  adaptive  Huffman  code.  If  no  file  names  are  given,  stan- 
dard input  is  compacted  and  sent  to  the  standard  output,  compact  operates  as  an  on-line  algorithm. 
Each  time  a  byte  is  read,  it  is  encoded  immediately  according  to  the  current  prefix  code.  This  code  is  an 
optimal  Huffman  code  for  the  set  of  frequencies  seen  so  far.  It  is  unnecessary  to  attach  a  decoding  tree  in 
front  of  the  compressed  file  because  the  encoder  and  the  decoder  start  in  the  same  state  and  stay  synchron- 
ized. Furthermore,  compact  and  uncompact  can  operate  as  filters.  I  n  particular, 

...    |   compact    |   uncompact    |  ... 

operates  as  a  (very  slow)  no-op. 

When  an  argument  file  is  given,  it  is  compacted,  the  resulting  file  is  placed  in  file.  C,  and  file  is  unlinked. 
The  first  two  bytes  of  the  compacted  file  code  the  fact  that  the  file  is  compacted.  These  bytes  are  used  to 
prohibit  recompaction. 

The  amount  of  compression  to  be  expected  depends  on  the  type  of  file  being  compressed.  Typical  file  size 
reduction  (in  percent)  through  compression  are:  Text,  38%;  Pascal  Source,  43%;  C  Source,  36%;  and 
Binary,  19%. 

uncompact  restores  the  original  file  from  a  file  compressed  by  compact.  If  no  file  names  are  specified, 
standard  input  is  uncompacted  and  sent  to  the  standard  output. 

ccat  cats  the  original  file  from  a  file  compressed  by  compact,  without  uncompressing  the  file. 

Access  Control  Lists  (ACLs) 

On  systems  that  implement  access  control  lists,  when  a  new  file  is  created  with  the  effective  user  and  group 
id  of  the  caller,  the  original  file's  ACL  is  copied  to  the  new  file  after  being  altered  to  reflect  any  change  in 
ownership  (see  acl(5)  and  aclv(5)).  In  J  FS  file  systems,  files  created  by  compact,  uncompact  or  ccat 
do  not  inherit  their  parent  directory's  default  ACL  entries  (if  any),  but  instead  retain  their  original  ACLs. 
When  a  file  being  compacted  or  uncompacted  resides  on  a  J  FS  file  system,  and  the  compacted  or  uncom- 
pacted file  resides  on  an  HFS  file  system  (or  vice  versa),  as  the  result  of  ccat  or  the  use  of  compact  or 
uncompact  as  a  filter,  optional  ACL  entries  are  lost. 

WARNINGS 

On  short-filename  systems,  the  last  segment  of  the  file  name  must  contain  12  or  fewer  characters  to  allow 
space  for  the  appended  .C. 

DEPENDENCIES 
NFS 

Access  control  list  entries  of  networked  files  are  summarized  (as  returned  in  st_mode  by  stat  () ),  but 
not  copied  to  the  new  file  (see  stat(2)). 

FILES 

* .  C        compacted  file  created  by  compact,  removed  by  uncompact 

SEE  ALSO 

compress(l),  pack(l),  acl(5),  aclv(5). 

Gallager,  Robert  G.,  "Variations  on  a  Theme  of  Huffman,"  I.E.E.E.  Transactions  on  Information  Theory, 
vol.  IT-24,  no.  6,  November  1978,  pp.  668-674. 

AUTHOR 

compact  was  developed  by  Colin  L.  Mc  Master. 
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NAME 

compress,  uncompress,  zcat,  compressdir,  uncompressdir  -  compress  and  expand  data 

SYNOPSIS 

Compress  Files 

compress  [-d]  [-f  |-z]  [-z]  [-v]  [-c]  [-V]  [-b  maxbits]  [file  ...] 
uncompress  [-f]  [-v]  [-c]  [-V]  [file  ...] 
zcat  [-V]  [file  ...] 

Compress  Entire  Directory  Subtrees 

compressdir  [options]  [directory  ...] 

uncompressdir  [options]  [directory  ...] 
DESCRIPTION 

Thefollowing  commands  compress  and  uncompress  files  and  directory  subtrees  as  indicated: 

compress  Reduce  the  size  of  the  named  files  using  adaptive  Lempel-Ziv  coding.  If  reduc- 

tion is  possible,  each  file  is  replaced  by  a  new  file  of  the  same  name  with  the 
suffix  .  Z  added  to  indicate  that  it  is  a  compressed  file.  Original  ownership, 
modes,  access,  and  modification  times  are  preserved.  If  no  file  is  specified,  or  if 
-  isspecified,  standard  input  is  compressed  to  the  standard  output. 

uncompress  Restore  the  compressed  files  to  original  form.  Resulting  files  have  the  original 
filename,  ownership,  and  permissions,  and  the  .  z  filename  suffix  is  removed.  If 
no  file  is  specified,  or  if  -  is  specified,  standard  input  is  uncompressed  to  the 
standard  output. 

zcat  Restore  the  compressed  files  to  original  form  and  send  the  result  to  standard 

output.  If  no  file  is  specified,  or  if  -  isspecified,  standard  input  is  uncompressed 
to  the  standard  output. 

compressdir  Front-end  processor.  Recursively  descend  each  specified  directory  subtree  and 
use  compress  to  compress  each  file  in  directory.  Existing  files  are  replaced  by 
a  compressed  file  having  the  same  name  plus  the  suffix  .  Z,  provided  the  result- 
ing file  is  smaller  than  the  original.  If  no  directories  are  specified,  compression 
is  applied  to  all  files  starting  with  the  current  directory. 

options  may  include  any  valid  compress  command  options  (they  are  passed 
through  to  compress).  To  force  compression  of  all  files,  even  when  the  result 
is  larger  than  the  original  file,  use  the  -f  option. 

uncompressdir    Opposite  of  compressdir.  Restore  compressed  files  to  their  original  form. 

options  may  include  any  valid  uncompress  command  options  (they  are  passed 
through  to  uncompress ). 

The  amount  of  compression  obtained  depends  on  the  size  of  the  input,  the  maximum  number  of  bits  (max- 
bits) per  code,  and  the  distribution  of  common  substrings.  Typically,  text  such  as  source  code  or  English  is 
reduced  by  50-60  percent.  Compression  is  generally  much  better  than  that  achieved  by  Huffman  coding  (as 
used  in  pack),  or  adaptive  Huffman  coding  (compact),  and  takes  less  time  to  compute. 

Options 

These  commands  recognize  thefollowing  options  in  the  combinations  shown  above  in  SYNOPSIS: 

-d  Decompress  file,  compress  -d  is  equivalent  to  uncompress  . 

-f  Force  compression  of  file.  This  is  useful  for  compressing  an  entire  directory, 

even  if  some  of  the  files  do  not  actually  shrink.  If  -f  is  not  given  and 
compress  is  run  in  the  foreground,  the  user  is  prompted  as  to  whether  an 
existing  fileshould  be  overwritten. 

-z  This  is  the  same  as  the  -f  option  except  that  it  does  not  force  compression 

when  there  is  null  compression. 

-v  Print  a  message  describing  the  percentage  of  reduction  for  each  file  compressed. 

-c  Force  compress  and  uncompress  to  write  to  the  standard  output;  no  files 

are  changed.  The  nondestructive  behavior  of  zcat  is  identical  to  that  of 
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uncompress  -c. 

-V  Print  the  current  version  and  compile  options  onto  the  standard  error. 

-b  maxbits  Specify  the  maximum  number  of  bits  the  compress  algorithm  will  use.  The 

default  is  16  and  the  range  can  beany  integer  between  9  and  16. 

compress  uses  the  modified  Lempel-Ziv  algorithm  popularized  in  A  Techniquefor  High  Performance  Data 
Compression  ,  Terry  A.  Welch,  IEEE  Computer,  vol.  17,  no.  6  (J  une  1984),  pages  8-19.  Common  substrings 
in  the  file  are  first  replaced  by  9-bit  codes  257  and  up.  When  code  512  is  reached,  the  algorithm  switches  to 
10-bit  codes  and  continues  to  use  more  bits  until  the  limit  specified  by  the  -b  flag  is  reached  (default  16). 

After  the  maxbits  limit  is  attained,  compress  periodically  checks  the  compression  ratio.  If  it  is  increas- 
ing, compress  continues  to  use  the  existing  code  dictionary.  However,  if  the  compression  ratio  is 
decreasing,  compress  discards  the  table  of  substrings  and  rebuilds  it  from  scratch.  This  allows  the  algo- 
rithm to  adapt  to  the  next  "block"  of  the  file. 

Note  that  the  -b  flag  is  omitted  for  uncompress  since  the  maxbits  parameter  specified  during  compres- 
sion is  encoded  within  the  output,  along  with  a  magic  number  to  ensure  that  neither  decompression  of  ran- 
dom data  nor  recompression  of  compressed  data  is  attempted. 

Access  Control  Lists 

compress  retains  a  file's  access  control  list  when  compressing  and  expanding  data. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  compress,  uncompress,  and  zcat 
behave  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

These  commands  return  the  foil  owing  values  upon  completion: 

0  Completed  successfully. 

2     Last  file  is  larger  after  (attempted)  compression. 

1  An  error  occurred. 

DIAGNOSTICS 

Usage:   compress    [-f|-z]    [-dvcV]    [-b  maxbits]    [file  ...] 

I  nvalid  options  were  specified  on  the  command  line. 

Missing  maxbits 

maxbits  must  follow  -b. 

file:  not  in  compressed  format 

The  file  specified  to  uncompress  has  not  been  compressed. 

file:  compressed  withxxbits,    can  only  handle  yybits 

file  was  compressed  by  a  program  that  could  deal  with  a  higher  value  of  maxbits  than  the  compress 
code  on  this  machine.  Recompress  the  file  with  a  lower  value  of  maxbits. 

file:   already  has    .  Z  suffix  —  no  change 

The  file  is  assumed  to  be  already  compressed.  Rename  the  file  and  try  again. 

file:   filename  too  long  to  tack  on   .  Z 

The  output  file  name,  which  is  the  source  file  name  with  a  .  Z  extension,  is  too  long  for  the  file  system 
on  which  the  source  file  resides.  Make  the  source  file  name  shorter  and  try  again. 

file  already  exists;    do  you  wish  to  overwrite    (y  or  n) ? 

Respond  y  ifyou  want  the  output  to  replace  the  existing  file;  otherwise,  respond  n. 
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uncompress:    corrupt  input 

A  SIGSEGV  violation  was  detected  which  usually  means  that  the  input  file  has  been  corrupted. 

Compression:  xx.xx% 

Percentage  of  the  input  saved  by  compression.  (Relevant  only  for  -v.) 

—  not  a  regular  file :  unchanged 

When  the  input  file  is  not  a  regular  file  (a  directory  for  example),  it  is  left  unaltered. 

—  has  xxother  links :  unchanged 

The  input  file  has  links  which  are  not  symbolic  links  and  has  been  left  unchanged.  See  I n (1)  for  more 
information. 

—  has  symbolic  links :  unchanged 

The  input  file  has  symbolic  links  and  has  been  left  unchanged.  See  I n (1)  for  more  information. 

—  file  unchanged 

No  savings  is  achieved  by  compression.  The  input  remains  unaltered. 

EXAMPLES 

Compress  the  file  named  zenith  and  print  compression  information  to  the  terminal: 

compress  -v  zenith 
The  terminal  display  shows  either  a  line  resembling 

zenith:    Compression:    23.55%  —  replaced  with  zenith. Z 
indicating  that  the  compressed  file  is  23.55%  smaller  than  the  original,  or  a  line  resembling 

zenith:    Compression:    -12.04%  —  file  unchanged 

indicating  that  an  additional  12.04%  space  must  be  used  to  compress  the  file. 

Undo  the  compression  by  typing  either  of  the  foil  owing  commands: 

uncompress   zenith. Z 
compress  -d  zenith. Z 

This  restores  file  zenith.  Z  to  its  original  uncompressed  form  and  name. 

uncompress  will  perform  on  standard  input  if  no  files  are  specified.  For  example,  to  list  a  compressed 
tar  file: 

uncompress  -c  arch. tar. Z    |   tar  -tvf  - 
WARNINGS 

Although  compressed  files  are  compatible  between  machines  with  large  memory,  -bl2  should  be  used  for 
filetransfer  to  architectures  with  a  small  process  data  space  (64K  bytes  or  less). 

NFS 

Access  control  lists  of  networked  files  are  summarized  (as  returned  in  st_mode  by  stat()  ,  but  not 
copied  to  the  new  file  (see  stat(2)). 

AUTHOR 

compress  was  developed  byj  oseph  M.  Orost,  Kenneth  E.  Turkowski,  Spencer  W.  Thomas,  and  J  ames  A. 
Woods. 

FILES 

*  .  Z  Compressed  file  created  by  compress  and  removed  by  uncompress  . 

SEE  ALSO 

compact(l),  pack(l),  acl(5). 

STANDARDS  CONFORMANCE 

compress:  XPG4 
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NAME 

convert  -  convert  an  audio  file 
SYNOPSIS 

/opt/audio/bin/convert  [sourcefile]  [targetfile]  [-sfmt  format]  [-dfmt  format] 
[-ddata  data  type]  [-srate  rate]  [-drate  rate] 
[-schannels  number]  [-dchannels  number] 

DESCRIPTION 

This  command  converts  audiofiles  from  one  supported  file  format,  data  format,  sampling  rate,  and  number 
of  channels  to  another.  The  unconverted  file  is  retained  as  a  sourcefile. 

-sfmt  format  -dfmt  format 

are  the  file  formats  for  the  source  and  destination  files.  Each  format  can  be  one  of  these: 


au 

Sun  file  format 

snd 

NeXT  file  format 

wav 

Microsoft  RIFF  Waveform  file  format 

u 

MuLaw  format 

al 

ALaw 

116 

linear  16-bit  format 

lo8 

offset  (unsigned)  linear  8-bit  format 

18 

linear  8-bit  format 

If  you  omit  -sfmt,  convert  uses  the  header  or  filename  extension  in  the  source  file.  You  can  omit 
-dfmt  if  you  supply  a  filename  extension  for  the  destination  file. 

-ddata  data  type 

isthedata  type  for  the  destination  files,  datatypecan  be  one  of  these: 

u  MuLaw 

al  ALaw 

116  linear  16-bit 

lo8  offset  (unsigned)  linear  8-bit  data 
18    linear  8-bit  data 

If  you  omit  -ddata,  convert  uses  an  appropriate  data  type,  normally  the  data  type  of  the  source 
file. 

-srate  rate  -drate  rate 

are  the  number  of  samples  per  second  for  the  source  and  destination  file.  Typical  sampling  rates 
range  from  8  to  Ilk  (for  voice  quality)  to  44,100  (for  CD  quality).  You  can  use  k  to  indicate 
thousands.  For  example,  8k  means  8,000  samples  per  second. 

If  you  omit  -srate,  convert  uses  a  rate  defined  by  the  source  file  header  or  its  filename  exten- 
sion. For  a  raw  file  with  no  extension,  8,000  is  used.  By  playing  the  file,  you  can  determine  if  8,000 
sampl es  i  s  too  fast  or  too  si  ow. 

If  you  omit  -drate,  convert  uses  a  sampling  rate  appropriate  for  the  destination  file  format;  if 
possible,  it  matches  the  sampling  rate  of  the  source  file. 

-schannels  number  -dchannels  number 

are  the  number  of  channels  in  the  source  and  destination  files.  Use  1  for  mono;  2  for  stereo.  If  - 
schannels  is  omitted,  convert  uses  the  information  in  the  header;  for  raw  data  files,  it  uses 
mono. 

If  -dchannels  is  omitted,  convert  matches  what  was  used  for  the  source  file  (through  the 
header  or  -schannels  option);  for  raw  data  files,  it  uses  mono. 

EXAMPLES 

Convert  a  raw  data  file  to  a  headered  file. 
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cd  /opt/audio/bin 

convert     beep .116     beep . au 

Convert  a  raw  data  file  to  a  headered  file  when  the  source  has  no  extension,  was  sampled  at  11,025  per 
second,  and  has  stereo  data. 

cd  /opt/audio/bin 

convert     beep    beep.au  -sfmt  116  -srate  11025  -schannels  2 

To  save  disk  space,  convert  an  audio  file  with  CD  quality  sound  to  voice  quality  sound, 
cd  /opt/audio/bin 

convert  idea . au     idea2 . au  -ddata  u  -drate  8k  -dchannels  1 

AUTHOR 

convert  was  developed  by  HP. 

Sun  is  a  trademark  of  Sun  Microsystems,  Inc. 
NeXT  is  a  trademark  of  NeXT  Computers,  I  nc. 
Microsoft  isa  trademark  of  Microsoft  Corporation. 

SEE  ALSO 

audio(5),  asecure(lM),  aserver(lM),  attributes(l),  send  sound(l). 
Using  theAudio  Developer's  Kit 
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NAME 

cp  -  copy  files  and  directory  subtrees 

SYNOPSIS 

cp  [-f  l-i]  [-p]  [-e  extarg  ]  filel  new  file 

cp  [-f  |-i]  [-p]  [-e  extarg  ]  filel  [file2  ...]  dest  di  rectory 

cp  [-f  l-i]  [-p]  [-R|-r]  [-e  extarg  ]  directoryl  [directory2  ...]  destdi  rectory 

DESCRIPTION 

cp  copies: 

•  filel  to  new  or  existing  new  file, 

•  filel  to  existing  destdi  rectory, 

•  filel,  file2,  ...  to  existing  destdi  rectory, 

•  directory  subtree  directoryl,  to  new  or  existing  destdi  rectory,  or 

•  multiple  directory  subtrees  directoryl,  directory2,  ...  to  new  or  existing  destdi  rectory. 

cp  fails  if  filel  and  new  fileare  the  same  (be  cautious  when  using  shell  metacharacters).  When  destination 
is  a  directory,  one  or  more  files  are  copied  into  that  directory.  If  two  or  more  files  are  copied,  the  destina- 
tion must  be  a  directory.  When  copying  a  single  file  to  a  new  file,  if  new  file  exists,  its  contents  are  des- 
troyed. 

If  the  access  permissions  of  the  destination  destdi  rectory  or  existing  destination  file  newfile  forbid  writing, 
cp  aborts  and  produces  an  error  message  "cannot  create  file". 

To  copy  one  or  more  directory  subtrees  to  another  directory,  the  -r  option  is  required.  The  -r  option  is 
ignored  if  used  when  copying  a  file  to  another  file  or  files  to  a  directory. 

If  new  fileis  a  link  to  an  existing  file  with  other  links,  cp  overwrites  the  existing  file  and  retains  all  links. 
If  copying  a  filetoan  existing  file,  cp  does  not  change  existing  file  access  permission  bits,  owner,  or  group. 

When  copying  files  to  a  directory  or  to  a  new  file  that  does  not  already  exist,  cp  creates  a  new  file  with  the 
same  file  permission  bits  as  filel,  modified  by  the  file  creation  mask  of  the  user  if  the  -p  option  was  not 
specified,  and  then  bitwise  inclusively  ORed  with  SJRWXU.  The  owner  and  group  of  the  new  file  or  files 
are  those  of  the  user.  The  last  modification  time  of  new  file  (and  last  access  time,  if  new  filedid  not  exist) 
and  the  last  access  time  of  the  source  filel  are  set  to  the  time  the  copy  was  made. 

Options 

-i  (interactive  copy)  Cause  cp  to  write  a  prompt  to  standard  error  and  wait  for  a  response  before 
copying  a  file  that  would  overwrite  an  existing  file.  If  the  response  from  the  standard  input  is 
affirmative,  the  file  is  copied  if  permissions  allow  the  copy.  If  the  -i  (interactive)  and  -f 
(forced-copy)  options  are  both  specified,  the  -i  option  is  ignored. 

-f  Force  existing  destination  pathnames  to  be  removed  before  copying,  without  prompting  for 
confirmation.  This  option  has  the  effect  of  destroying  and  replacing  any  existing  file  whose  name 
and  directory  location  conflicts  with  the  name  and  location  of  the  new  file  created  by  the  copy 
operation. 

-p  (preserve  permissions)  Causes  cp  to  preserve  in  the  copy  as  many  of  the  modification  time,  access 
time,  file  mode,  user  I D,  and  group  I D  as  allowed  by  permissions. 

-r  (recursive  subtree  copy)  Cause  cp  to  copy  the  subtree  rooted  at  each  source  directory  to 
destdi  rectory.  If  destdi  rectory  exists,  it  must  be  a  directory,  in  which  case  cp  creates  a  direc- 
tory within  dest  di  rectory  with  the  same  name  as  filel  and  copies  the  subtree  rooted  at  filel  to 
destdi  rectory/  filel.  An  error  occurs  if  destdi  rectory/  filel  already  exists.  If  destdi  rectory  does 
not  exist,  cp  creates  it  and  copies  the  subtree  rooted  at  filel  to  dest  di  rectory.  Note  that  cp  -r 
cannot  merge  subtrees. 

Usually  normal  files  and  directories  are  copied.  Character  special  devices,  block  special  devices, 
network  special  files,  named  pipes,  symbolic  links,  and  sockets  are  copied,  if  the  user  has  access  to 
the  file;  otherwise,  a  warning  is  printed  stating  that  the  file  cannot  be  created,  and  the  file  is 
skipped. 

destdi  rectory  should  not  reside  within  directoryl,  nor  should  directoryl  have  a  cyclic  directory 
structure,  si  nee  in  both  cases  cp  attempts  to  copy  an  infinite  amount  of  data. 
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-R  (recursive  subtree  copy)  The  -R  option  is  identical  to  the  -r  option  with  the  exception  that  direc- 
tories copied  by  the  -R  option  are  created  with  read,  write,  and  search  permission  for  the  owner. 
User  and  group  permissions  remain  unchanged. 

With  the  -R  and  -r  options,  in  addition  to  regular  files  and  directories,  cp  also  copies  FIFOs, 
character  and  block  device  files  and  symbolic  links.  Only  superusers  can  copy  device  files.  All 
other  users  get  an  error.  Symbolic  links  are  copied  so  the  target  points  to  the  same  location  that 
the  source  did. 

Warning:  While  copying  a  directory  tree  that  has  device  special  files,  use  the  -r  option;  otherwise, 
an  infinite  amount  of  data  is  read  from  the  device  special  file  and  is  duplicated  as  a  special  file  in 
the  destination  directory  occupying  large  file  system  space. 

-e  extarg 

Specifies  the  handling  of  any  extent  attributes  of  the  file[s]  to  be  copied,  extarg  takes  one  of  the 
following  values. 

warn      Issues  a  warning  message  if  extent  attributes  cannot  be  copied,  but  copies  the  file 
anyway. 

ignore  Does  not  copy  the  extent  attributes. 

force     Failstocopy  the  file  if  the  extent  attributecan  not  becopied. 

Extent  attributes  can  not  becopied  if  the  files  are  being  copied  to  a  file  system  which  does  not  sup- 
port extent  attributes  or  if  that  file  system  has  a  different  block  size  than  the  original.  If  -e  is  not 
specified,  the  default  value  for  extarg  is  warn. 

Access  Control  Lists  (ACLs) 

If  new  file  is  a  new  file,  or  if  a  new  file  is  created  in  dest  di rectory,  it  inherits  the  access  control  list  of  the 
original  fil el,  file2,  etc.,  altered  to  reflect  any  difference  in  ownership  between  the  two  files  (seeacl(5)  and 
aclv(5)).  In  J  FS  file  systems,  new  files  created  by  cp  do  not  inherit  their  parent  directory's  default  ACL 
entries  (if  any),  but  instead  retain  the  ACLs  of  the  files  being  copied.  When  copying  files  from  a  J  FS  file 
system  to  an  HFS  file  system  or  vice  versa,  optional  ACL  entries  are  lost. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters. 

LANG  and  LC_CTYPE  determine  the  local  languageequivalent  of  y  (for  yes/no  queries). 
LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used 
as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an 
invalid  setting,  cp  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

The  following  command  moves  the  directory  sourcedir  and  its  contents  to  a  new  location  (targetdir)  in  the 
file  system.  Since  cp  creates  the  new  directory,  the  destination  directory  targetdir  should  not  already 
exist. 

cp  -r  sourcedir  targetdir  &&  rm  -rf  sourcedir 

The  -r  option  copies  the  subtree  (files  and  subdirectories)  in  directory  sourcedir  to  directory  targetdir. 
The  double  ampersand  (&&)  causes  a  conditional  action.  If  the  operation  on  the  left  side  of  the  &&  is  suc- 
cessful, the  right  side  is  executed  (and  removes  the  old  directory).  If  the  operation  on  the  left  of  the  &&  is 
not  successful,  the  old  directory  is  not  removed. 

This  example  is  equivalent  to: 

mv  sourcedir  targetdir 

To  copy  all  files  and  directory  subtrees  in  the  current  directory  to  an  existing  targetdir,  use: 
cp  -r  *  targetdir 
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To  copy  all  files  and  directory  subtrees  in  sourcedir  to  targetdir,  use: 

cp  -r  sourcedir/*  targetdir 

Note  that  directory  pathnames  can  precede  both  sourcedir  and  targetdir. 

To  create  a  zero-length  file,  use  any  of  the  following: 

cat  /dev/null  >file 
cp  /dev/null  file 
touch  file 

DEPENDENCIES 
NFS 

Access  control  lists  of  networked  files  are  summarized  (as  returned  in  st_mode  by  stat() ),  but  not 
copied  to  the  new  file.  When  using  mv  or  In  on  such  files,  a  +  is  not  printed  after  the  mode  value  when 
asking  for  permission  to  overwrite  a  file. 

AUTHOR 

cp  was  developed  by  AT&T,  the  University  of  California,  Berkeley,  and  HP. 
SEE  ALSO 

cpio(l),  ln(l),  mv(l),  rm(l),  link(lM),  lstat(2),  readlink(2),  stat(2),  symlink(2),  symlink(4),  acl(5),  aclv(5). 

STANDARDS  CONFORMANCE 

cp:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

cpio-  copy  file  archives  in  and  out;  duplicate  directory  trees 

SYNOPSIS 

cpio  -o  [-e  extarg  ]  [achvxABC] 

cpio  -i[bcdfmrstuvxBPRSU6]  [pattern...] 
cpio  -p  [-e  extarg  ]  [adlmruvxU]  directory 


DESCRIPTION 

The  cpio  command  saves  and  restores  archives  of  files  on  magnetic  tape,  other  devices,  or  a  regular  file, 
and  copies  files  from  one  directory  to  another  while  replicating  the  directory  tree  structure.  When  cpio 
completes  processing  the  files,  it  reports  the  number  of  blocks  written. 

cpio  -o  (copy  out,  export)  Read  standard  input  to  obtain  a  list  of  path  names,  and  copy  those  files  to 
standard  output  together  with  path  name  and  status  information.  The  output  is  padded  to  a 
512-byte  boundary. 

cpio  -i  (copy  in,  import)  Extract  files  from  standard  input,  which  is  assumed  to  be  the  result  of  a  pre- 
vious cpio  -o. 

If  pattern...,  is  specified,  only  the  files  with  names  that  match  a  pattern  according  to  the  rules 
of  Pattern  Matching  Notation  (see  regexp(5))  are  selected.  A  leading  !  on  a  pattern  indicates 
that  only  those  names  that  do  not  match  the  remainder  of  the  pattern  should  be  selected. 
Multiple  patterns  can  be  specified.  The  patterns  are  additive.  If  no  pattern  is  specified,  the 
default  is  *  (select  all  files).  Seethe  f  option,  as  well. 

Extracted  files  are  conditionally  created  and  copied  into  the  current  directory  tree,  as  deter- 
mined by  the  options  described  below.  The  permissions  of  the  files  match  the  permissions  of 
the  original  files  when  the  archive  was  created  by  cpio  -o  unless  the  U  option  is  used.  File 
owner  and  group  are  that  of  the  current  user  unless  the  user  has  appropriate  privileges,  in 
which  case  cpio  retains  the  owner  and  group  of  the  files  of  the  previous  cpio  -o. 

cpio  -p  (passthrough)  Read  standard  input  to  obtain  a  list  of  path  names  of  files  which  are  then  con- 
ditionally created  and  copied  into  the  destination  directory  tree  as  determined  by  the  options 
described  below,  directory  must  exist.  Destination  path  names  are  interpreted  relative  to 
directory. 

With  the  -p  option,  when  handling  a  link,  only  the  link  is  passed  and  no  data  blocks  are  actu- 
ally read  or  written.  This  is  especially  noteworthy  with  cpio  -pi,  where  it  is  very  possible 
that  all  the  files  are  created  as  links,  such  that  no  blocks  are  written  and  "0  blocks"  is  reported 
by  cpio.  (See  below  for  a  description  of  the  -1  option.) 


Options 

cpio  recognizes  the  following  options,  which  can  be  appended  as  appropriate  to  -i,  -o,  and  -p.  Whi- 
tespace  and  hyphens  are  not  permitted  between  these  options  and  -i,  -o,  or  -p. 

a         Reset  access  times  of  input  files  after  they  are  copied. 

b         Swap  both  bytes  and  half-words.  Use  only  with -i.  See  the  P  option  for  details;  see  also  the 
s  and  S  options. 

c         Write  or  read  header  information  i n  ASCI  I  character  form  for  portability, 
d         Create  directories  as  needed, 
-e  extarg 

Specifies  the  handling  of  any  extent  attributes  of  the  file(s)  to  be  archived  or  copied,  extarg 
takes  one  of  the  fol I owi  ng  val ues. 

warn      Archive  or  copy  the  file  and  issue  a  warning  message  if  extent  attributes  cannot 
be  preserved. 

ignore  Do  not  issue  a  warning  message  even  if  extent  attributes  cannot  be  preserved, 
force     Any  file(s)  with  extent  attributes  will  not  be  archived  and  a  warning  message 
will  be  issued. 

When  using  the  -o  option,  extent  attributes  are  not  preserved  in  the  archive.  Furthermore, 
the  -p  option  will  not  preserve  extent  attributes  if  the  files  are  being  copied  to  a  file  system 
that  does  not  support  extent  attributes.  If  -e  is  not  specified,  the  default  value  for  extarg  is 
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warn . 

f         Copy  in  all  files  except  those  selected  by  pattern.... 

h  Follow  symbolic  links  as  though  they  were  normal  files  or  directories.  Normally,  cpio 
archives  the  link. 

1  Whenever  possible,  link  files  rather  than  copying  them.  This  option  does  not  destroy  existing 
files.  Use  only  with -p. 

m  Retain  previous  file  modification  time.  This  option  does  not  affect  directories  that  are  being 
copied. 

r         Rename  files  interactively.  If  the  user  types  a  null  line,  the  file  is  skipped. 

s  Swap  all  bytes  of  the  file.  Use  only  with -i.  See  the  P  option  for  details;  see  also  the  s  and 
S  options. 

t         Print  only  a  tableof  contents  of  the  input.  No  files  are  created,  read,  or  copied. 

u  Copy  unconditionally  (normally,  an  older  file  does  not  replace  a  newer  file  with  the  same 
name). 

v  Print  a  list  of  file  names  as  they  are  processed.  When  used  with  the  t  option,  the  table  of 
contents  has  the  format: 

numeric-mode  owner-name  blocks  date-time  filename 

where  numeric-mode  is  the  file  privileges  in  numeric  format,  owner-name  is  the  name  of  the 
file  owner,  blocks  is  the  size  of  the  file  in  512-byte  blocks,  date-time  is  the  date  and  time  the 
file  was  last  modified,  and  filename  is  the  path  name  of  the  file  as  recorded  in  the  archive. 

x  Save  or  restore  device  special  files.  Since  mknod()  is  used  to  recreate  these  files  on  a 
restore,  -ix  and  -px  can  be  used  only  by  users  with  appropriate  privileges  (see  mknod(2)). 
This  option  is  intended  for  intrasystem  (backup)  use  only.  Restoring  device  files  from  previ- 
ous versions  of  the  OS,  or  from  different  systems  can  be  very  dangerous,  cpio  may  prevent 
the  restoration  of  certain  device  files  from  the  archive. 

A  Suppress  warning  messages  regarding  optional  access  control  list  entries,  cpio  does  not 
back  up  optional  access  control  list  entries  in  a  file's  access  control  list  (see  acl  (5)).  Normally, 
a  warning  message  is  printed  for  each  filethat  has  optional  access  control  list  entries. 

B  Block  input/output  at  5120  bytes  to  the  record  (does  not  apply  to  cpio  -p).  This  option  is 
meaningful  only  with  data  directed  to  or  from  devices  that  support  variable-length  records 
such  as  magnetic  tape. 

C  Have  cpio  checkpoint  itself  at  the  start  of  each  volume.  If  cpio  is  writing  to  a  streaming 
tape  drive  with  immediate-report  mode  enabled  and  a  write  error  occurs,  it  normally  aborts 
and  exits  with  return  code  2.  With  this  option  specified,  cpio  instead  automatically  restarts 
itself  from  the  checkpoint  and  rewrites  the  current  volume.  Alternatively,  if  cpio  is  not 
writing  to  such  a  device  and  a  write  error  occurs,  cpio  normally  continues  with  the  next 
volume.  With  this  option  specified,  however,  the  user  can  choose  to  either  ignore  the  error  or 
rewrite  the  current  volume. 

P  Read  a  file  written  on  a  PDP-11  or  VAX  system  (with  byte-swapping)  that  did  not  use  the  c 
option.  Use  only  with -i.  Files  copied  in  this  mode  are  not  changed.  Non-ASCII  files  are 
likely  to  need  further  processing  to  be  readable.  This  processing  often  requires  knowledge  of 
file  contents,  and  thus  cannot  always  be  done  by  this  program.  Theb,  s,  and  S  options  can 
be  used  when  swapping  all  the  bytes  on  the  tape  (rather  than  just  in  the  headers)  is  appropri- 
ate. I  n  general,  text  is  best  processed  with  P  and  binary  data  with  one  of  the  other  options. 

(PDP-11  and  VAX  are  registered  trademarks  of  Digital  Equipment  Corporation.) 

R         Resynchronize automatically  when  cpio  goes  "out  of  phase",  (see diagnostics). 

5  Swap  all  half-words  in  the  file.  Use  only  with -i.  See  the  P  option  for  details;  see  also  theb 
and  s  options. 

U  Use  the  process's  file-mode  creation  mask  (see  umask(2))  to  modify  the  mode  of  files  created, 
in  the  same  manner  as  creat(2). 

6  Process  a  UNIX  Sixth-Edition-format  file.  Use  only  with -i. 
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Note  that  cpio  archives  created  using  a  raw  device  file  must  be  read  using  a  raw  device  file. 

When  the  end  of  the  tape  is  reached,  cpio  prompts  the  user  for  a  new  special  file  and  continues. 

If  you  want  to  pass  one  or  more  metacharacters  to  cpio  without  the  shell  expanding  them,  be  sure  to  pre- 
cede each  of  them  with  a  backslash  (\). 

Device  files  written  with  the  -ox  option  (such  as  /dev/tty03)  do  not  transport  to  other  implementa- 
tions of  HP-UX. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  pattern  matching  notation  for  file 
name  generation. 

LC_CTYPE  determines  the  interpretation  of  text  as  singleand/or  multi-byte  characters,  and  the  characters 
matched  by  character  class  expressions  in  pattern  matching  notation. 

LC_TIME  determines  the  format  and  content  of  date  and  time  strings  output  when  listing  the  contents  of 
an  archive  with  the  v  option. 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_COLLATE,  LC_CTYPE,  or  LC_TIME  is  not  specified  in  the  environment  or  is  set  to  the  empty 
string,  the  value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not 
specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  interna- 
tionalization variable  contains  an  invalid  setting,  cpio  behaves  as  if  all  internationalization  variables  are 
set  to  "C".  See  environ (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

cpio  returns  the  following  exit  codes: 

0  Successful  completion.  Review  standard  error  for  files  that  could  not  be  transferred. 

1  Error  during  resynchronization.  Some  files  may  not  have  been  recovered. 

2  Out-of-phase error.  A  file  header  is  corrupt  or  in  the  wrong  format. 

DIAGNOSTICS 

Out  of  phase — get  help 

Perhaps  the  "c"  option  should[n't]    be  used 

cpio  -i  could  not  read  the  header  of  an  archived  file.  The  header  is  corrupt  or  it  was  written  in  a 
different  format.  Without  the  R  option,  cpio  returns  an  exit  code  of  2. 

If  no  file  name  has  been  displayed  yet,  the  problem  may  be  the  format.  Try  specifying  a  different 
header  format  option:  null  for  standard  format;  c  for  ASCII;  b,  s,  P,  or  S,  for  one  of  the  byte- 
swapping  formats;  or  6  for  UNIX  Sixth  Edition. 

Otherwise,  a  header  may  be  corrupt.  Use  the  R  option  to  have  cpio  attempt  to  resynchronize  the 
file  automatically.  Resynchronizing  means  that  cpio  tries  to  find  the  next  good  header  in  the  archive 
file  and  continues  processing  from  there.  If  cpio  tries  to  resynchronize  from  being  out  of  phase,  it 
returns  an  exit  code  of  1. 

Other  diagnostic  messages  are  self-explanatory. 

EXAMPLES 

Copy  the  contents  of  a  directory  into  a  tape  archive: 

Is    |   cpio  -o  >  /dev/rmt/cOtOdOBEST 

Duplicate  a  directory  hierarchy: 
cd  olddir 

find  .  -depth  -print    |   cpio  -pd  newdir 
Thetrivial  case 
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find   .   -depth  -print    |   cpio  -oB  >/dev/rmt/cOtOdOBEST 
can  be  handled  more  efficiently  by: 

find   .   -cpio  /dev/rmt/cOtOdOBEST 
WARNINGS 

Because  of  industry  standardsand  interoperability  goals,  cpio  does  not  support  the  archival  of  files  larger 
than  2GB  or  files  that  have  user/group  I  Ds  greater  than  60K.  Files  with  user/group  I  Ds  greater  than  60K 
are  archived  and  restored  under  the  user/group  I D  of  the  current  process. 

Do  not  redirect  the  output  of  cpio  to  a  named  cpio  archive  file  residing  in  the  same  directory  as  the  ori- 
ginal files  belonging  to  that  cpio  archive.  This  can  cause  loss  of  data. 

cpio  strips  any  leading  .  /  characters  in  the  list  of  filenames  piped  to  it. 

Path  names  are  restricted  to  PATH_MAX  characters  (see  <limits.h>  and  limits(5)).  If  there  are  too 
many  unique  linked  files,  the  program  runs  out  of  memory  to  keep  track  of  them.  Thereafter,  linking  infor- 
mation is  lost.  Only  users  with  appropriate  privileges  can  copy  special  files. 

cpio  tapes  written  on  hp  machines  with  the  -ox[c]  options  can  sometimes  mislead  (non-HP)  versions  of 
cpio  that  do  not  support  the  x  option.  If  a  non-HP  (or  n  on -AT&T)  version  of  cpio  happens  to  be  modified 
so  that  the  (hp)  cpio  recognizes  it  as  a  device  special  file,  a  spurious  device  file  might  be  created. 

If  /dev/tty  is  not  accessible,  cpio  issues  a  complaint  and  exits. 

The-pd  option  does  not  create  the  di  rectory  typed  on  the  command  line. 

The-idr  option  does  not  make  empty  directories. 

The-plu  option  does  not  link  files  to  existing  files. 

posix  defines  a  file  named  TRAILER!  !  !  as  an  end-of-archive  marker.  Consequently,  if  a  file  of  that 
name  is  contained  in  a  group  of  files  being  written  by  cpio  -o,  the  file  is  interpreted  as  end-of-archive, 
and  no  remaining  files  are  copied.  The  recommended  practice  is  to  avoid  naming  files  anything  that  resem- 
bles an  end-of-archive  file  name. 

To  create  a  POSix-conforming  cpio  archive,  the  c  option  must  be  used.  To  read  a  POSix-conforming  cpio 
archive,  the  c  option  must  be  used  and  theb,  s,  S,  and  6  options  should  not  be  used.  If  the  user  does  not 
have  appropriate  privileges,  theu  option  must  also  be  used  to  get  POSix-conforming  behavior  when  reading 
an  archive.  Users  with  appropriate  privileges  should  not  use  this  option  to  get  POSix-conforming  behavior. 

DEPENDENCIES 

If  the  path  given  to  cpio  contains  a  symbolic  link  as  the  last  element,  this  link  is  traversed  and  pathname 
resolution  continues,    cpio  uses  the  symbolic  link's  target,  rather  than  that  of  the  link. 

SEE  ALSO 

ar(l),  find(l),  tar(l),  cpio(4),  acl(5),  environ(5),  lang(5),  regexp(5). 

STANDARDS  CONFORMANCE 

cpio:  SVI D2,  SVI D3,  XPG2,  XPG3 
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NAME 

cpp  -  the  C  language  preprocessor 


SYNOPSIS 

/usr/ccs/lbin/cpp  [option  ...]  [ifile  [ofile]] 


DESCRIPTION 

cpp  is  the  C  language  preprocessor  which  is  invoked  as  the  first  pass  of  any  C  compilation  using  the  cc 
command  (see  cc(l)).  Its  purpose  is  to  process  finclude  and  conditional  compilation  instructions  and 
macros.  Thus  the  output  of  cpp  is  designed  to  be  in  a  form  acceptable  as  input  to  the  next  pass  of  the  C 
compiler.  As  the  C  language  evolves,  cpp  and  the  rest  of  the  C  compilation  package  will  be  modified  to  fol- 
low these  changes.  Therefore,  the  use  of  cpp  in  other  than  this  framework  is  not  suggested.  The  pre- 
ferred way  to  invoke  cpp  is  through  the  cc  command,  since  the  functionality  of  cpp  may  someday  be 
moved  elsewhere.  See  m4(l)  for  a  general  macro  processor. 

cpp  optionally  accepts  two  file  names  as  arguments,  ifile  and  ofile  are  respectively  the  input  and  output 
for  the  preprocessor.  They  default  to  standard  input  and  standard  output  if  not  specified. 


Options 

Thefollowing  options  are  recognized  by  cpp: 

Remove  all  predefined  symbols  that  begin  with  a  letter  and  _HPUX_SOURCE  .  The  user  is 
expected  to  define  _POSlX_SOURCE  or  _XOPEN_SOURCE  when  using  this  option. 

By  default,  cpp  strips  C-style  comments.  If  the  -C  option  is  specified,  all  comments 
(except  those  found  on  cpp  directive  lines)  are  passed  along. 


-A 


-C 


-Dname 
-Dname=def 


-Hnnn 


-h[inclfile] 


-Idir 


-M[  makefile] 


-P 
-T 


-Una  me 


Define  nameas  if  by  a  fdefine  directive.  If  no  =def  is  given,  name  is  defined  as  1.  The 
-D  option  has  lower  precedence  than  the  -U  option.  Thus,  if  the  same  name  is  used  in 
both  a  -U  option  and  a  -D  option,  the  name  is  undefined  regardless  of  the  order  of  the 
options. 

Change  the  internal  macro  definition  tableto  be  nnn  bytes  in  size.  The  default  buffer  size 
is  at  least  8188  bytes.  This  option  serves  to  eliminate  "Macro  param  too  large",  "Macro 
invocation  too  large",  "Macro  param  too  large  after  substitution",  "Quoted  macro  param  too 
large",  "Macro  buffer  too  small",  "Input  line  too  long",  and  "Catenated  input  line  too  long" 
errors. 

Generates  included  files  and  sents  the  results  to  the  file  inclfile.  If  the  argument  inclfile  is 
omitted,  the  result  is  sent  to  the  standard  error. 

Change  the  algorithm  for  searching  for  finclude  files  whose  names  do  not  begin  with  / 
to  look  in  dir  before  looking  in  the  directories  on  the  standard  list.  Thus,  finclude  files 
whose  names  are  enclosed  in  double  quotes  (" ")  are  searched  for  first  in  the  directory  of 
the  file  containing  the  #include  line,  then  in  directories  named  in  -I  options  in  left-to- 
right  order,  and  last  in  directories  on  a  standard  list.  For  finclude  files  whose  names 
are  enclosed  in  angle  brackets  (<>),  the  directory  of  the  file  containing  the  #include  line 
is  not  searched.  However,  directory  dir  is  still  searched. 

Generates  makefile  dependencies  and  sends  the  results  to  the  file  makefile.  If  the  argu- 
ment makefile  is  omitted,  the  result  is  sent  to  the  standard  error. 

Preprocess  the  input  without  producing  the  line-control  information  used  by  the  next  pass 
of  the  C  compiler. 

hp-ux  no  longer  restricts  preprocessor  symbols  to  eight  characters.  The  -T  option  forces 
cpp  to  use  only  the  first  eight  characters  for  distinguishing  different  preprocessor  names. 
This  behavior  is  the  same  as  preprocessors  on  some  other  systems  with  respect  to  the 
length  of  names,  and  is  included  for  backward  compatibility. 

Remove  any  initial  definition  of  name,  where  name  is  a  reserved  symbol  that  is  predefined 
by  the  particular  preprocessor.  Thecurrent  list  of  these  symbols  includes: 

Operating  system:        unix   unix 

Hardware:  hp9000s200  hp9000s300   hp9000s300 

hp9000s500  hp9000s800   hp9000s800 

hp9000ipc  hppa   hppa 
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_PA_RISC1_0         _PA_RISC1_1         _SIO  _WSIO 

UNIX  systems  variant:   hpux   hpux  _HPUX_SOURCE 

PWB  _PWB 

lint(l):  lint   lint 

In  addition,  all  symbols  that  begin  with  an  underscore  and  either  an  upper-case  letter  or 
another  underscore  are  reserved.  Other  symbols  may  be  defined  by  the  CCOPTS  variable 
or  other  command-line  options  to  the  C  compiler  at  compile  time  (see  cc(l)).  All  hp-ux  sys- 
tems have  the  symbols  PWB,  hpux,  unix,  _PWB,  hpux,  and  unix  defined.  Each 

system  defines  at  least  one  hardware  variant,  as  appropriate.  The  lint  symbols  are  defined 
when  lint(l)  is  running.  See  dependencies. 

Two  special  names  are  understood  by  cpp.  LINE  is  defined  as  the  current  line  number  (as  a 

decimal  integer)  as  counted  by  cpp.  FILE  is  defined  as  the  current  file  name  (as  a  C  string)  as 

known  by  cpp.  They  can  be  used  anywhere  (including  in  macros)  just  as  any  other  defined  names. 

Directives 

All  cpp  directives  start  with  lines  begun  by  #.  Any  number  of  blanks  and  tabs  are  allowed  between  the  # 
and  the  directive.  The  directives  are: 

#define  name  token-string 

Replace  subsequent  instances  of  name  with  token-string,  token-string  can  be  null. 

#def  ine  name(arg,   ...  ,  arg)  token-string 

Replace  subsequent  instances  of  name  followed  by  a  (,  a  list  of  comma-separated  set  of 
arguments,  and  a  )  by  token-string,  where  each  occurrence  of  an  arg  in  the  token-stri ng  is 
replaced  by  the  corresponding  set  of  tokens  in  the  comma-separated  list.  When  a  macro 
with  arguments  is  expanded,  the  arguments  are  placed  into  the  expanded  token-string 
unchanged.  After  the  entire  token-string  has  been  expanded,  cpp  restarts  its  scan  for 
names  to  expand  at  the  beginning  of  the  newly  created  token-string. 

Notice  that  there  can  be  no  space  between  nameandthe  (. 

fendif  [text] 

Ends  a  section  of  lines  begun  by  a  test  directive  (#if ,  #ifdef ,  or  #ifndef ).  Each  test 
directive  must  have  a  matching  fendif.  Any  text  occurring  on  the  same  line  as  the 
#endif  is  ignored  and  thus  may  be  used  to  mark  matching  #if-#endif  pairs.  This 
makes  it  easier,  when  reading  the  source,  to  match  #if ,  #ifdef ,  and  fifndef  direc- 
tives with  their  associated  fendif  directive. 

#eiif  constant-expression 

Equivalent  to: 


#else 


#else 

#if  constant-expression 

Reverses  the  notion  of  the  test  directive  that  matches  this  directive.  Thus,  if  lines  previous 
to  this  directive  are  ignored,  the  foil  owing  lines  appear  in  the  output,  and  vice  versa. 

#if  constant-expression 

The  lines  following  appear  in  the  output  if  and  only  if  the  constant-expression  evaluates  to 
nonzero.  All  binary  nonassignment  C  operators,  the  ?:  operator,  the  unary  -,  !,  and  ~ 
operators  are  all  legal  in  constant-expression.  The  precedence  of  the  operators  is  the  same 
as  defined  by  the  C  language. 

There  is  also  a  unary  operator,  defined,  which  can  be  used  in  constant-expression  in 
these  two  forms:  defined  (  name)  or  defined  name  This  allows  the  use  of  #ifdef 
and  fifndef  in  an  #if  directive. 

Only  these  operators,  integer  constants,  and  names  that  are  known  by  cpp  should  be  used 
inconstant-expression.  In  particular,  the  sizeof  operator  is  not  available. 

#ifdef  name 
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The  lines  foil  owing  appear  in  the  output  if  and  only  if  name  has  been  the  subject  of  a  previ- 
ous #def  ine  without  being  the  subject  of  an  intervening  #undef . 

#ifndef  name 

The  lines  foil  owing  do  not  appear  in  the  output  if  and  only  if  name  has  been  the  subject  of  a 
previous  #def  ine  without  being  the  subject  of  an  intervening  #undef . 

#inciude  "filename' 
#inciude  <filename> 

I  nclude  at  this  point  the  contents  of  filename  (which  are  then  run  through  cpp).  See  the 
-I  option  above  for  more  detail. 

#iine  integer-constant  "filename' 

Causes  cpp  to  generate  line-control  information  for  the  next  pass  of  the  C  compiler, 
integer-constant  is  the  line  number  of  the  next  line  and  filename  is  the  file  where  it  comes 
from.  If  filename  and  the  quotation  marks  are  omitted,  the  current  file  name  is  unchanged. 

#undef  name 

Cause  the  definition  of  name  (if  any)  to  be  forgotten  from  now  on. 

The  test  directives  and  the  possible  #else  directives  can  be  nested,  cpp  supports  names  up  to  255  char- 
acters in  length. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  comments  and  string  literals  as  single-  or  multibyte  charac- 
ters. 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used  as 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  it 
defaults  to  "C"  (see  lang(5)).  If  any  internationalization  variable  contains  an  invalid  setting,  cpp  behaves 
asifall  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

DIAGNOSTICS 

Error  messages  produced  by  cpp  are  intended  to  be  self-explanatory.  The  I  ine  number  and  filename  where 
the  error  occurred  are  printed  along  with  the  diagnostic. 

WARNINGS 

When  newl ine  characters  were  found  in  argument  lists  for  macros  to  be  expanded,  previous  versions  of  cpp 
put  out  the  newlines  as  they  were  found  and  expanded.  The  current  version  of  cpp  replaces  these  new- 
lines  with  blanks  to  alleviate  problems  that  the  previous  versions  had  when  this  occurred. 

DEPENDENCIES 

Series  700 

The  symbols  hp9000s700  and  hp9000s700  are  not  reserved  symbols  recognized  by  the  -U  option. 

They  are  supplied  to  cpp  either  automatically  by  the  compiler,  or  by  the  use  of  a  compiler  option.  For 
example,  on  a  Series  700  system,  the  command: 

cc  -v  t .  c 

produces: 

/usr/ccs/lbin/cpp  t.c  /var/tmp/ctmAAAa29220  -D  hp9000s700 

-D  hp9000s800  ... 

(Also  see  the -D  option  of  thecc  command.) 
FILES 

/usr/include      Standard  directory  for  finclude  files 
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SEE  ALSO 

m4(l). 

NOTES 

The  macro  substitution  scheme  has  been  changed.  Previous  versions  of  cpp  saved  macros  in  a  macro 
definition  table  whose  table  size  is  128000  bytes  by  default.  The  current  version  of  cpp  replaces  this 
macro  definition  tablewith  several  small  buffers.  Thedefault  size  of  the  small  buffers  is8188  bytes. 

STANDARDS  CONFORMANCE 

cpp:  SVID2,  SVID3,  XPG2 
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NAME 

crontab-  user  job  file  scheduler 

SYNOPSIS 

crontab  [file] 

crontab  -e  [username] 
crontab  -1  [username] 
crontab  -r  [username] 

DESCRIPTION 

The  crontab  command  manages  a  crontab  file  for  the  user.  You  can  use  a  crontab  file  to  schedule  jobs 
that  are  executed  automatically  by  cron  (see  cron(lM))  on  a  regular  basis.  Thecommand  has  four  forms: 

crontab  [file]  Create  or  replace  your  crontab  file  by  copying  the  specified  file,  or  standard 

input  if  file  is  omitted  or  -  is  specified  as  file  ,  into  the  crontab  directory, 
/var/spool/cron/crontabs.  The  name  of  your  crontab  file  in  the 
crontab  di  rectory  is  the  same  as  your  effective  user  name. 

crontab  -e  [username] 

Edit  a  copy  of  the  user's  crontab  file,  or  create  an  empty  file  to  edit  if  the 
crontab  file  does  not  exist.  When  editing  is  complete,  the  file  will  be  copied 
i  nto  the  crontab  di  rectory  as  the  user's  crontab  fil  e. 

crontab  -1  [username] 

Lists  the  user's  crontab  file. 

crontab  -r  [username] 

Remove  the  user's  crontab  file  from  the  crontab  directory. 

Only  a  privileged  user  can  use  username  foil  owing  the -e,  -I,  or  -r  options,  to  edit,  list,  or  remove  the  cron- 
tab file  of  the  specified  user. 

The  entries  in  a  crontab  file  are  lines  of  six  fields  each.  The  fields  are  separated  by  spaces  or  tabs.  The 
I  i  nes  have  the  fol  I  owi  ng  format: 

minute  hour  monthday  month  weekday  command 

The  first  five  are  integer  patterns  that  specify  when  the  sixth  field,  command,  should  be  executed.  They 
can  have  the  fol  I  owing  ranges  of  values: 

minute  Theminuteof  the  hour,  0-59 

hour  The  hour  of  the  day,  0-23 

monthday  The  day  of  the  month,  1-31 

month  The  month  of  the  year,  1-12 

weekday  The  day  of  the  week,  0-6,  0=Sunday 

Each  pattern  can  be  either  an  asterisk  (*),  meaning  all  legal  values,  or  a  list  of  elements  separated  by  com- 
mas. An  element  is  either  a  number  in  the  ranges  shown  above,  or  two  numbers  in  the  range  separated  by 
a  hyphen  (meaning  an  inclusive  range).  Note  that  the  specification  of  days  can  be  made  in  two  fields: 
monthday  and  weekday.  If  both  are  specified  in  an  entry,  they  are  cumulative.  For  example, 

0      0      1,15      *      1  command 

runs  command  at  midnight  on  the  first  and  fifteenth  of  each  month,  as  well  as  every  Monday.  To  specify 
days  in  only  one  field,  set  the  other  field  to  asterisk  (*).  For  example, 

0      0**1  command 

runs  command  only  on  Mondays. 

The  sixth  field,  command  (the  balance  of  a  line  including  blanks  in  a  crontab  file),  is  a  string  that  is  exe- 
cuted by  the  shell  at  the  specified  times.  A  percent  character  (%)  in  this  field  (unless  escaped  bya  backslash 
(\))  is  translated  to  a  newline  character,  dividing  the  field  into  "lines".  Only  the  first  "line"  (up  to  a  %  or 
end-of-line)  of  the  command  field  is  executed  by  the  shell.  Any  other  "lines"  are  made  avail  able  to  the  com- 
mand as  standard  input. 
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Blank  lines  and  those  whose  first  non-blank  character  is#will  beignored. 

cron  invokes  the  command  from  the  user's  HOME  directory  with  the  POSIX  shell,  (/usr/bin/sh).  It 
runs  i  n  the  c  queue  (see  queuedefs(4)). 

cron  suppliesa  default  environment  for  every  shell,  defining: 

HOME=  user's-home-di  rectory 
logname=  user's-l  ogi  n-i  d 
PATH=/usr/bin : /usr/sbin : . 
SHELL=/usr/bin/sh 

Users  who  desire  to  have  their  .profile  executed  must  explicitly  do  so  in  the  crontab  entry  or  in  a  script 
called  by  the  entry. 

You  can  execute  crontab  if  your  name  appears  in  the  file  /usr/lib/cron/cron .  allow.  If  that  file 
does  not  exist,  you  can  use  crontab  if  your  name  does  not  appear  in  the  file 
/usr/lib/cron/cron . deny.  If  only  cron. deny  exists  and  is  empty,  all  users  can  use  crontab. 
If  neither  file  exists,  only  the  root  user  can  use  crontab.  The  allow/deny  files  consist  of  one  user 
name  per  line. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  within  file  as  single- and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  crontab  behaves  as  if  all  internationali- 
zation variables  are  set  to  "C".  See  environ (5).  EDITOR  determines  the  editor  to  be  invoked  when  -e 
option  isspecified.  Thedefault  editor  isvi. 

I  nternational  Code  Set  Support 

Single-byte  and  multi-byte  character  code  sets  are  supported. 


Be  sure  to  redirect  the  standard  output  and  standard  error  from  commands.  If  this  is  not  done,  any  gen- 
erated standard  output  or  standard  error  is  mailed  to  the  user. 


WARNINGS 


FILES 


/ var / adm/ cron 


Main  cron  directory 
List  of  allowed  users 
List  of  denied  users 


/ var/ adm/ cron/ cron . allow 
/ var/ adm/ cron/ cron . deny 
/ var/ adm/ cron/ log 


Accounting  information 

Directory  containing  the  crontab  files 


/var/ spool/cron/ crontabs 


SEE  ALSO 

sh(l),  cron(lM),  queuedefs(4). 


STANDARDS  CONFORMANCE 

crontab:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4 
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NAME 

crypt  -  encode/decode  files 

SYNOPSIS 

crypt  [  password  ] 

DESCRIPTION 

crypt  reads  from  the  standard  input  and  writes  on  the  standard  output,  password  is  a  key  that  selects  a 
particular  transformation.  If  no  password  is  given,  crypt  demands  a  key  from  the  terminal  and  turns  off 
printing  whilethe  key  is  being  typed  in.    crypt  encrypts  and  decrypts  with  the  same  key: 

crypt  key  <clear  >cypher 
crypt  key  <cypher  |  pr 

The  latter  command  decrypts  the  file  and  prints  the  clear  version. 

Files  encrypted  by  crypt  are  compatible  with  those  treated  by  the  ed  editor  in  encryption  mode  (see 
ed(l)). 

Security  of  encrypted  files  depends  on  three  factors:  the  fundamental  method  must  be  hard  to  solve;  direct 
search  of  the  key  space  must  be  infeasible;  "sneak  paths"  by  which  keys  or  clear  text  can  become  visible 
must  be  minimized. 

crypt  implements  a  one-rotor  machine  designed  along  the  lines  of  the  German  Enigma,  but  with  a  256- 
element  rotor.  Methods  of  attack  on  such  machines  are  widely  known;  thus  crypt  provides  minimal  secu- 
rity. 

The  transformation  of  a  key  into  the  internal  settings  of  the  machine  is  deliberately  designed  to  be  expen- 
sive; i.e.,  to  take  a  substantial  fraction  of  a  second  to  compute.  However,  if  keys  are  restricted  to,  for  exam- 
ple, three  lowercase  letters,  then  encrypted  files  can  be  read  by  expending  only  a  substantial  fraction  of  five 
minutes  of  machine  time. 

Since  the  key  is  an  argument  to  the  crypt  command,  it  is  potentially  visibleto  users  executing  the  ps  or 
a  derivative  (see  ps(l)).  The  choice  of  keys  and  key  security  are  the  most  vulnerable  aspect  of  crypt. 

EXAMPLES 

The  following  example  demonstrates  the  use  of  crypt  to  edit  a  file  that  the  user  wants  to  keep  strictly 
confidential: 

$  crypt  <plans  >plans . x 
key :  vi  ol  et 
$  rm  plans 

$  vi  -x  plans . x 

key :  vi  ol  et 

:  wq 
$ 

$  crypt  <plans . x    |  pr 
key :  vi  ol  et 

Note  that  the  -x  option  is  the  encryption  mode  of  vi,  and  prompts  the  user  for  the  same  key  with  which 
the  file  was  encrypted. 

WARNINGS 

If  output  is  piped  to  nroff  and  the  encryption  key  is  not  given  on  the  command  line,  crypt  can  leave 
termi  nal  modes  i  n  a  strange  state  (see  nroff  (1)  and  stty  (1)). 

If  two  or  more  files  encrypted  with  the  same  key  are  concatenated  and  an  attempt  is  made  to  decrypt  the 
result,  only  the  the  first  of  the  original  files  is  decrypted  correctly. 

FILES 

/dev/tty  for  typed  key 
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SEE  ALSO 

ed(l),  makekey(l),  stty(l). 
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NAME 

csh  -  a  shell  (command  interpreter)  with  C-l ike  syntax 
SYNOPSIS 

csh  [-cef instvxTVX]  [commandfile]  [ argument  l ist  ...] 
DESCRIPTION 

csh  isa  command  language  interpreter  that  incorporates  a  command  history  buffer,  C-l  ike  syntax,  and  job 
control  facilities. 

Command  Options 

Command  options  are  interpreted  as  follows: 

-c  Read  commands  from  the  (single)  following  argument  which  must  be  present.  Any  remain- 

ing arguments  are  placed  in  argv. 

-e  C  shell  exits  if  any  invoked  command  terminates  abnormally  or  yields  a  non-zero  exit 

status. 

-f  Suppress  execution  of  the  .cshrc  file  in  your  home  directory,  thus  speeding  up  shell 

start-up  time. 

-i  Force  csh  to  respond  interactively  when  called  from  a  device  other  than  a  computer  ter- 

minal (such  as  another  computer),  csh  normally  responds  non-interactively.  If  csh  is 
called  from  a  computer  terminal,  it  always  responds  interactively,  regardless  of  which 
options  are  selected. 

-n  Parse  but  do  not  execute  commands.  This  is  useful  for  checking  syntax  in  shell  scripts.  All 

substitutions  are  performed  (history,  command,  alias,  etc.). 

-s  Take  command  input  from  the  standard  input. 

-t  Read  and  execute  a  single  line  of  input. 

-v  Set  the  verbose  shell  variable,  causing  command  input  to  be  echoed  to  the  standard  out- 

put device  after  history  substitutions  are  made. 

-x  Set  the  echo  shell  variable,  causing  all  commands  to  be  echoed  to  the  standard  error 

immediately  before  execution. 

-T  Disable  the  tenex  features  which  use  the  ESC  key  for  command/file  name  completion  and 

CTRL-D  for  listing  availablefiles  (see  the  CSH  UTILITIES  section  below) 

-V  Set  the  verbose  variable  before  .cshrc  is  executed  so  that  all   .cshrc  commands 

are  also  echoed  to  the  standard  output. 

-X  Set  the  echo  variable  before  .cshrc  is  executed  so  that  all   .cshrc  commands  are 

also  echoed  to  the  standard  output. 

After  processing  the  command  options,  if  arguments  remain  in  the  argument  list,  and  the  -c,  -i,  -s,  or 
-t  options  were  not  specified,  the  first  remaining  argument  is  taken  as  the  name  of  a  file  of  commands  to 
be  executed. 

COMMANDS 

A  simple  command  is  a  sequence  of  words,  the  first  of  which  specifies  the  command  to  be  executed.  A 
sequence  of  simple  commands  separated  by  vertical  bar  ( | )  characters  forms  a  pipeline.  The  output  of  each 
command  in  a  pipeline  becomes  the  input  for  the  next  command  in  the  pipeline.  Sequences  of  pipelines  can 
be  separated  by  semicolons  (; )  which  causes  them  to  be  executed  sequentially.  A  sequence  of  pipelines  can 
be  executed  in  background  mode  by  adding  an  ampersand  character  (&)  after  the  last  entry. 

Any  pipelinecan  be  placed  in  parentheses  to  form  a  simple  command  which,  in  turn,  can  bea  component  of 
another  pipeline.  Pipelines  can  also  be  separated  by  |  |  or  &&  indicating,  as  in  the  C  language,  that  the 
second  pipelineisto  be  executed  only  if  the  first  failsor  succeeds,  respectively. 

J  obs 

csh  associates  a  job  with  each  pipeline  and  keeps  a  table  of  current  jobs  (printed  by  the  jobs  command) 
and  assigns  them  small  integer  numbers.  When  a  job  is  started  asynchronously  using &,  the  shell  prints  a 
line  resembling: 
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[1]  1234 

indicating  that  thejob  which  was  started  asynchronously  was  job  number  1  and  had  one  (top-level)  process, 
whose  process  id  was  1234. 

If  you  are  running  a  job  and  want  to  do  something  else,  you  can  type  the  currently  defined  suspend  charac- 
ter (see  termio(7))  which  sends  a  stop  signal  to  the  current  job.  csh  then  normally  indicates  that  thejob 
has  been  'Stopped',  and  prints  another  prompt.  You  can  then  manipulate  the  state  of  this  job,  putting  it  in 
the  background  with  the  bg  command,  run  some  other  commands,  and  then  eventually  bring  thejob  back 
into  the  foreground  with  the  foreground  command  fg.  A  suspend  takes  effect  immediately  and  is  like  an 
interrupt  in  that  pending  output  and  unread  input  are  discarded  when  it  is  typed.  There  is  a  delayed 
suspend  character  which  does  not  generate  a  stop  signal  until  a  program  attempts  to  read(2)  it.  This  can 
usefully  be  typed  ahead  when  you  have  prepared  some  commands  for  a  job  which  you  want  to  stop  after  it 
has  read  them. 

A  job  being  run  in  the  background  stops  if  it  tries  to  read  from  the  terminal.  Background  jobs  are  normally 
allowed  to  produce  output,  but  this  can  be  disabled  by  giving  the  command  stty  tostop  (see  stty(l)). 
If  you  set  this  tty  option,  background  jobs  stop  when  they  try  to  produce  output,  just  as  they  do  when  they 
try  to  read  input.  Keyboard  signals  and  line-hangup  signals  from  the  terminal  interface  are  not  sent  to 
background  jobs  on  such  systems.  This  means  that  background  jobs  are  immune  to  the  effects  of  logging 
out  or  typing  the  interrupt,  quit,  suspend,  and  delayed  suspend  characters  (see  termio(7)). 

There  are  several  ways  to  refer  tojobs  in  the  shell.  The  character  %  introduces  a  job  name.  If  you  wish  to 
refer  to  job  number  1,  you  can  name  it  as  %1.  J  ust  naming  a  job  brings  it  to  the  foreground;  thus  %1  is  a 
synonymfor  fg  %1  ,  bri  nging  job  1  back  into  the  foreground.  Similarly,  typing  %1  &  resumes  job  1  in 
the  background.  J  obs  can  also  be  named  by  prefixes  of  the  string  typed  in  to  start  them  if  these  prefixes 
are  unambiguous;  thus  %ex  normally  restarts  a  suspended  ex(l)  job,  if  there  is  only  one  suspended  job 
whose  name  begins  with  the  string  ex.  It  is  also  possible  to  say  %?string  which  specifies  a  job  whose 
text  contains  string,  if  there  is  only  one  such  job. 

csh  maintains  a  notion  of  the  current  and  previous  jobs.  In  output  pertaining  to  jobs,  the  current  job  is 
marked  with  a  +  and  the  previous  job  with  a -.  The  abbreviation  %+  refers  to  the  current  job  and  %- 
refers  to  the  previous  job.  For  close  analogy  with  the  syntax  of  the  history  mechanism  (described  below), 
%%  is  also  a  synonymfor  the  current  job. 

csh  learns  immediately  whenever  a  process  changes  state.  It  normally  informs  you  whenever  a  job 
becomes  blocked  so  that  no  further  progress  is  possible,  but  only  just  before  printing  a  prompt.  This  is  done 
so  that  it  does  not  otherwise  disturb  your  work.  If,  however,  you  set  the  shell  variable  notify,  csh 
notifies  you  immediately  of  changes  in  status  of  background  jobs.  There  is  also  a  csh  built-in  command 
called  notify  which  marks  a  single  process  so  that  any  status  change  is  immediately  reported.  By 
default,  notify  marks  the  current  process.  Simply  type  notify  after  starting  a  background  job  to 
mark  it. 

If  you  try  to  leave  the  shell  while  jobs  are  stopped,  csh  sends  the  warning  message:  You  have 
stopped  jobs.  Usethe  jobs  command  to  see  what  they  are.  If  you  dothisor  immediately  try  toexit 
again,  csh  does  not  warn  you  a  second  time,  and  the  suspended  jobs  are  terminated  (see  exit(2)). 

Built-in  Commands 

Built-in  commands  are  executed  within  the  shell  without  spawning  a  new  process.  If  a  built-in  command 
occurs  as  any  component  of  a  pipeline  except  the  last,  it  is  executed  in  a  subshell.  The  built-in  commands 
are: 

alias 
alias  name 
alias  namewordlist 

The  first  form  prints  all  aliases.  The  second  form  prints  the  alias  for  name.  The  third  form 
assigns  the  specified  wordlist  as  the  alias  of  name.  Command  and  file  name  substitution  are 
performed  on  wordlist.  namecannot  be  alias  or  unalias. 

bg  [%job  ...] 

Put  the  current  (job  not  specified)  or  specified  jobs  into  the  background,  continuing  them  if 
they  were  stopped. 

break  Causes  execution  to  resume  after  the  end  of  the  nearest  enclosing  foreach  or  while. 
The  remaining  commands  on  the  current  line  are  executed.  Multi-level  breaks  are  thus  possi- 
ble by  writing  them  all  on  one  line. 
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breaksw 

Causes  a  break  from  a  switch,  resuming  after  the  endsw. 
case  label  : 

A  label  in  a  switch  statement  as  discussed  below. 

cd 

cd  directoryname 
chdir 

chdir  directory  name 

Change  the  shell's  current  working  directory  to  directory  name.  If  not  specified, 
di  rectoryname  defaults  to  your  home  di rectory. 

If  directory  name  is  not  found  as  a  subdirectory  of  the  current  working  directory  (and  does 
not  begin  with  /,  ./,  or  .  ./),  each  component  of  the  variable  cdpath  is  checked  to  see  if  it 
has  a  subdirectory  directory  name.  Finally,  if  all  else  fails,  csh  treats  directory  name  as  a 
shell  variable.  If  its  value  begins  with  /,  this  is  tried  to  see  if  it  is  a  directory.  See  alsocd(l). 

continue 

Continue  execution  of  the  nearest  enclosing  while  or  foreach.  The  rest  of  the  commands 
on  the  current  line  are  executed. 

default : 

Labels  the  default  case  in  a  switch  statement.  The  default  should  come  after  all  other 
case  labels. 

dirs  Prints  the  directory  stack;  the  top  of  the  stack  is  at  the  left;  the  first  directory  in  the  stack  is 
the  current  directory. 

echo  wordlist 
echo  -n  wordlist 

The  specified  words  are  written  to  the  shell's  standard  output,  separated  by  spaces,  and  ter- 
minated with  a  new-lineunlessthe  -n  option  is  specified.  See  also  echo(l). 

else 

end 

endif 

endsw  See  the  descriptions  of  the  foreach,  if,  switch,  and  while  statements  below, 
eval  arguments ... 

(Same  behavior  as  sh(l).)  arguments  are  read  as  input  to  the  shell  and  the  resulting 
command(s)  executed.  This  is  usually  used  to  execute  commands  generated  as  the  result  of 
command  or  variablesubstitution,  since  parsing  occurs  before  these  substitutions. 

exec  command 

The  specified  command  is  executed  in  place  of  the  current  shell. 

exit 

exit  (expression) 

csh  exits  either  with  the  value  of  the  status  variable  (first  form)  or  with  the  value  of  the 
specified  expression  (second  form). 

fg  [%job  ...] 

Brings  the  current  (job  not  specified)  or  specified  jobs  into  the  foreground,  continuing  them  if 
they  were  stopped. 

foreach  name  (wordlist) 

end  The  variable  name  is  successively  set  to  each  member  of  wordlist  and  the  sequence  of  com- 
mands between  this  command  and  the  matching  end  are  executed.  (Both  foreach  and 
end  must  appear  alone  on  separate  lines.) 

The  built-in  command  continue  can  be  used  to  continue  the  loop  prematurely;  the  built-in 
command  break  to  terminate  it  prematurely.  When  this  command  is  read  from  the  termi- 
nal, the  loop  is  read  once,  prompting  with  ?  before  any  statements  in  the  loop  are  executed. 
If  you  make  a  mistake  while  typing  in  a  loop  at  the  terminal,  use  the  erase  or  line-kill  charac- 
ter as  appropriate  to  recover. 

glob  wordlist 

Like  echo  but  no  \  escapes  are  recognized  and  words  are  delimited  by  null  characters  in 
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the  output.  Useful  in  programs  that  use  the  shell  to  perform  file  name  expansion  on  a  list  of 
words. 

goto  word 

The  specified  word  is  file  name  and  command  expanded  to  yield  a  string  of  the  form  label. 
The  shell  rewinds  its  input  as  much  as  possible  and  searches  for  a  line  of  the  form  label : 
possibly  preceded  by  blanks  or  tabs.  Execution  continues  after  the  specified  line. 

hashstat 

Print  a  statistics  line  indicating  how  effective  the  internal  hash  table  has  been  at  locating 
commands  (and  avoiding  execs).  An  exec  is  attempted  for  each  component  of  the  path 
where  the  hash  function  indicates  a  possible  hit,  and  in  each  component  that  does  not  begin 
with  a  /. 

history  [-h][-r][n] 

Displays  the  history  event  list.  If  n  is  given,  only  the  n  most  recent  events  are  printed.  The 
-r  option  reverses  the  order  of  printout  to  be  most  recent  first  rather  than  oldest  first.  The 
-h  option  prints  the  history  list  without  leading  numbers  for  producing  files  suitablefor  the 
source  command. 

if  (expression)  command 

If  expression  evaluates  true,  the  single  command  with  arguments  is  executed.  Variable  sub- 
stitution on  command  happens  early,  at  the  same  time  it  does  for  the  rest  of  the  if  com- 
mand, command  must  bea  simple  command;  not  a  pipeline,  a  command  list,  a  parenthesized 
command  list,  or  an  aliased  command.  Input/output  redirection  occurs  even  if  expression  is 
false,  meaning  that  command  is  not  executed  (this  is  a  bug). 

if  (expressionl)  then 
else  if  (expression2)  then 
else 

endif  If  expressionl  is  true,  all  commands  down  to  the  first  else  are  executed;  otherwise  if 
expression2  is  true,  all  commands  from  the  first  else  down  to  the  second  else  are  exe- 
cuted, etc.  Any  number  of  else-if  pairs  are  possible,  but  only  one  endif  is  needed.  The 
else  part  is  likewiseoptional.  (Thewords  else  and  endif  must  appear  at  the  beginning 
of  input  lines.  The  if  must  appear  aloneon  its  input  lineor  after  an  else.) 

jobs  [-1] 

Lists  active  jobs.  The  -1  option  I  i  sts  process  I  ds  i  n  addition  to  the  usual  information. 

kill  %  job 

kill  -  sig  %  job  ... 

kill  pid 

kill  -sig  pid... 

kill  -1 

Sends  either  the  term  (terminate)  signal  or  the  specified  signal  to  the  specified  jobs  or 
processes.  Signals  are  either  given  by  number  or  by  names  (as  given  in 
/usr/include/signal  .h,  stripped  of  the  SIG  prefix  (see  signal  (2)).  The  signal  names 
are  listed  by  kill  -1.  There  is  no  default,  so  kill  used  alone  does  not  send  a  signal  to 
the  current  job.  If  the  signal  being  sent  isTERM  (terminate)  or  hup  (hangup),  the  job  or  pro- 
cess is  sent  a  CONT  (continue)  signal  as  well.  See  also  kill(l). 

limit[-h][  resource]!  maximumuse] 

Limits  the  usage  by  the  current  process  and  each  process  it  creates  not  to  (individually) 
exceed  maximumuse  on  the  specified  resource.  If  maximumuse  is  not  specified,  then  the 
current  limit  isdisplayed;  if  resource  is  not  specified,  then  all  limitationsare  given. 

If  the  -h  flag  is  specified,  the  hard  limits  are  used  instead  of  the  current  limits.  The  hard 
limits  impose  a  ceiling  on  the  values  of  the  current  limits.  Only  the  superuser  can  raise  the 
hard  limits,  but  a  user  can  lower  or  raise  the  current  limits  within  the  legal  range. 

Controllable  resources  currently  include: 

addresspace       Maximum  address  space  in  bytes  for  a  process 
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memoryuse 
stacksize 


coredumpsize 

cputime 

datasize 


descriptors 
f ilesize 


Size  of  the  largest  core  dump  that  is  created 

Maximum  number  of  CPU  seconds  to  be  used  by  each  process 

Maximum  growth  of  the  data  region  allowed  beyond  the  end  of  the 
program  text 

Maximum  number  of  open  files  for  each  process 

Largest  singlefilethat  can  be  created 

Maximum  size  to  which  a  process's  resident  set  size  can  grow 

Maximum  size  of  the  automatically  extended  stack  region 


The  maximumuse  argument  can  be  specified  as  a  floating-point  or  integer  number  followed 
by  a  scalefactor:  kor  kilobytes  (1024  bytes),  m  or  megabytes,  or  bor  blocks  (the  units  used  by 
the  ulimit  system  call).  For  both  resource  names  and  scale  factors,  unambiguous  prefixes  of 
the  names  can  be  used,  filesize  can  be  lowered  by  an  instance  of  csh,  but  can  only  be  raised 
by  an  instance  whose  effective  user  I D  is  root.  For  more  information,  refer  to  the  documenta- 
tion for  the  ulimit  system  call. 

login  Terminates  a  login  shell,  replacing  it  with  an  instance  of  /usr/bin/login.  This  is  one 
way  to  log  off,  included  for  compatibility  with  sh(l). 


Terminates  a  login  shell.  Especially  useful  if  ignoreeof  is  set.  A  similar  function,  bye,  which 
works  for  sessions  that  are  not  login  shells,  is  provided  for  historical  reasons.  Its  use  is  not 
recommended  because  it  is  not  part  of  the  standard  BSD  csh  and  may  not  be  supported  in 
future  releases. 


Changes  the  group  identification  of  the  caller;  for  details  see  newgrp(l).  A  new  shell  is  exe- 
cuted by  newgrp  so  that  the  current  shell  environment  is  lost. 

nice 

nice  +number 

nice  command 

nice  +number  command 

The  first  form  sets  the  nice  (run  command  priority)  for  this  shell  to  4  (the  default).  The 
second  form  sets  the  priority  to  the  given  number.  The  final  two  forms  run  command  at 
priority  4  and  number  respectively.  The  user  with  appropriate  privileges  can  raise  the  prior- 
ity by  specifying  negative  niceness  using  nice  -number  ...  command  is  always  executed  in 
a  sub-shell,  and  restrictions  placed  on  commands  in  simple  if  statements  apply.  See  also 
nice(l). 

nohup  [command] 

Without  an  argument,  nohup  can  be  used  in  shell  scripts  to  cause  hangups  to  be  ignored  for 
the  remainder  of  the  script.  With  an  argument,  causes  the  specified  command  to  be  run  with 
hangups  ignored.  All  processes  executed  in  the  background  with  &  are  effectively  nohuped 
as  described  under  J  obs  in  theCOMMANDS  section. 

notify  [job  ...] 

Causes  the  shell  to  notify  the  user  asynchronously  when  the  status  of  the  current  (job  not 
specified)  or  specified  jobs  changes;  normally  notification  is  presented  before  a  prompt.  This 
is  automatic  if  the  shell  variable  notify  is  set. 

onintr  [-]  [label  ] 

Controls  the  action  of  the  shell  on  interrupts.  With  no  arguments,  onintr  restores  the  default 
action  of  the  shell  on  interrupts,  which  action  is  to  terminate  shell  scripts  or  return  to  the  ter- 
minal command  input  level.  If  -  is  specified,  all  interrupts  are  ignored.  If  a  label  is  given, 
the  shell  executes  a  goto  label  when  an  interrupt  is  received  or  a  child  process  terminates 
because  it  was  interrupted. 

If  the  shell  is  running  in  the  background  and  interrupts  are  being  ignored,  onintr  has  no 
effect;  interrupts  continue  to  be  ignored  by  the  shell  and  all  invoked  commands. 


Pops  the  directory  stack,  returning  to  the  new  top  directory.  With  an  argument,  discards  the 
n  th  entry  in  the  stack.  The  elements  of  the  directory  stack  are  numbered  from  0  starting  at 


logout 


newgrp 


popd  [+n] 
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the  top.  A  synonym  for  popd,  called  rd,  is  provided  for  historical  reasons.  Its  use  is  not 
recommended  because  it  is  not  part  of  the  standard  BSD  csh  and  may  not  be  supported  in 
future  releases. 

pushd  [name]  [+n] 

With  no  arguments,  pushd  exchanges  the  top  two  elements  of  the  directory  stack.  Given  a 
name  argument,  pushd  changes  to  the  new  directory  (using  cd)  and  pushes  the  old  current 
working  directory  (as  in  csw)  onto  the  directory  stack.  With  a  numeric  argument,  pushd 
rotates  the  n  th  argument  of  the  directory  stack  around  to  be  the  top  element  and  changes  to 
that  directory.  The  members  of  the  directory  stack  are  numbered  from  the  top  starting  at  0. 
A  synonym  for  pushd,  called  gd,  is  provided  for  historical  reasons.  Its  use  is  not  recom- 
mended since  it  is  not  part  of  the  standard  BSD  csh  and  may  not  be  supported  in  future 
releases. 

rehash 

Causes  the  internal  hash  table  of  the  contents  of  the  directories  in  the  path  variable  to  be 
recomputed.  This  is  needed  if  new  commands  are  added  to  directories  in  the  path  whileyou 
are  logged  in.  This  should  only  be  necessary  if  you  add  commands  to  one  of  your  own  direc- 
tories or  if  a  systems  programmer  changes  the  contents  of  one  of  the  system  directories. 

repeat  count  command 

The  specified  command  (which  is  subject  to  the  same  restrictions  as  the  command  in  the  one- 
line  if  statement  above)  is  executed  count  times.  I/O  redirections  occur  exactly  once,  even  if 
count  isO. 

set 

set  name 

set  name=word 

set  name [  index  ]  =word 

set  name=  (  word  list ) 

The  first  form  of  set  shows  the  value  of  all  shell  variables.  Variables  whose  value  is  other 
than  a  single  word  print  as  a  parenthesized  word  list.  The  second  form  sets  name  to  the  null 
string.  The  third  form  sets  name  to  the  single  word.  The  fourth  form  sets  the  indexth  com- 
ponent of  name  to  word;  this  component  must  already  exist.  The  final  form  sets  name  to  the 
list  of  words  in  wordlist.  I  n  all  cases  the  value  is  command  and  file-name  expanded. 

These  arguments  can  be  repeated  to  set  multiple  values  in  a  singleset  command.  Note,  how- 
ever, that  variable  expansion  happens  for  all  arguments  before  any  setting  occurs. 

setenv  name  value 

Sets  the  value  of  environment  variable  name  to  be  value,  a  single  string.  The  most  commonly 
used  environment  variables,  USER,  TERM,  and  PATH,  are  automatically  imported  to  and 
exported  from  the  csh  variables  user,  term,  and  path;  there  is  no  need  to  use  setenv  for 
these. 

shift  [variable] 

If  no  argument  is  given,  the  members  of  argv  are  shifted  to  the  left,  discarding  argv  [1]  . 
An  error  occurs  if  argv  is  not  set  or  has  less  than  two  strings  assigned  to  it.  When  variable 
is  specified,  shift  performs  the  same  function  on  the  specified  variable. 

source  [-h]  name 

csh  reads  commands  from  name,  source  commands  can  be  nested,  but  if  nested  too  dee- 
ply the  shell  may  run  out  of  file  descriptors.  An  error  in  a  source  at  any  level  terminates 
all  nested  source  commands.  Normally,  input  during  source  commands  is  not  placed  on 
the  history  list.  The  -h  option  can  be  used  to  place  commands  in  the  history  list  without 
bei  ng  executi  ng  them. 

stop  [%job  ...] 

Stops  the  current  (no  argument)  or  specified  jobs  executing  in  the  background, 
suspend 

Causes  csh  to  stop  as  if  it  had  been  sent  a  suspend  signal.  Since  csh  normally  ignores 
suspend  signals,  this  is  the  only  way  to  suspend  the  shell.  This  command  gives  an  error  mes- 
sage if  attempted  from  a  login  shell. 

switch  (string) 
case  strl : 
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breaksw 
default : 
breaksw 

endsw  Each  case  label  (strl)  is  successively  matched  against  the  specified  string  which  is  first 
command  and  file  name  expanded.  The  form  of  the  case  labels  is  the  Pattern  Matching 
Notation  with  the  exception  that  non-matching  lists  in  bracket  expressions  are  not  supported 
(see  regexp(5)).  If  none  of  the  labels  match  before  a  default  label  is  found,  the  execution 
begi ns  after  the  default  label.  Each  case  label  and  the  default  label  must  appear  at 
the  beginning  of  a  line.  The  breaksw  command  causes  execution  to  continue  after  the 
endsw.  Otherwise,  control  may  fall  through  case  labels  and  default  labels  as  in  C.  If 
no  label  matches  and  there  is  no  default,  execution  continues  after  the  endsw. 

time  [command] 

When  command  is  not  specified,  a  summary  of  time  used  by  this  shell  and  its  children  is 
printed.  If  specified,  the  simple  command  is  timed  and  a  time  summary  as  described  under 
the  time  variable  is  printed.  If  necessary,  an  extra  shell  is  created  to  print  the  time  statis- 
tic when  the  command  completes. 

umask  [value] 

The  current  file  creation  mask  is  displayed  (value  not  specified)  or  set  to  the  specified  value. 
The  mask  is  given  in  octal.  Common  values  for  the  mask  are  002,  which  gives  all  permis- 
sions to  the  owner  and  group  and  read  and  execute  permissions  to  all  others,  or  022,  which 
gives  all  permissions  to  the  owner,  and  only  read  and  execute  permission  to  the  group  and  all 
others.  See  also  umask(l). 

unalias  pattern 

All  aliases  whose  names  match  the  specified  pattern  are  discarded.  Thus,  all  aliases  are 
removed  by  unalias  *.  No  error  occurs  if  pattern  does  not  match  an  existing  alias. 

unhash 

Use  of  the  internal  hash  table  to  speed  location  of  executed  programs  is  disabled, 
unset  pattern 

All  variables  whose  names  match  the  specified  pattern  are  removed.  Thus,  all  variables  are 
removed  by  unset  *;  this  has  noticeably  undesirable  si  de-effects.  No  error  occurs  if  pattern 
matches  nothing. 

unsetenv  pattern 

Removes  all  variables  whose  names  match  the  specified  pattern  from  the  environment.  See 
also  the  setenv  command  above  and  printenv(l). 

wait  Waits  for  all  background  jobs  to  terminate.  If  the  shell  is  interactive,  an  interrupt  can  dis- 
rupt the  wait,  at  which  time  the  shell  prints  names  and  job  numbers  of  all  jobs  known  to  be 
outstanding. 

while  (expression) 

end  While  the  specified  expression  evaluates  non-zero,  the  commands  between  the  while  and 
the  matching  end  are  evaluated,  break  and  continue  can  be  used  to  terminate  or 
continue  the  loop  prematurely.  (The  while  and  end  must  appear  alone  on  their  input 
lines.)  If  the  input  is  a  terminal  (i.e.,  not  a  script),  prompting  occurs  the  first  time  through 
the  loop  as  for  the  foreach  statement. 

%job     Brings  the  specified  job  into  the  foreground. 

%job  &  Continues  the  specified  job  in  the  background. 

@ 

@  name=expression 

@  name[index]  =expression 

The  first  form  prints  the  values  of  all  the  shell  variables.  The  second  form  sets  the  specified 
name  to  the  value  of  expression.  If  the  expression  contains  <,>,&,  or  | ,  at  least  this  part  of 
the  expression  must  be  placed  within  parentheses.  The  third  form  assigns  the  value  of 
expression  to  the  indexth  argument  of  name.  Both  name  and  its  indexth  component  must 
already  exist. 
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The  operators  *=,  +=,  etc.,  are  available  as  in  C.  White  space  can  optionally  separate  the 
name  from  the  assignment  operator.  However,  spaces  are  mandatory  in  separating  com- 
ponents of  expression  which  would  otherwise  be  single  words. 

Special  postfix  ++  and  —  operators  increment  and  decrement  name,  respectively  (e.g., 
@  i++). 

Non-Built-ln  Command  Execution 

When  a  command  to  be  executed  is  not  a  built-in  command,  csh  attempts  to  execute  the  command  via 
exec(2).  Each  word  in  the  variable  path  names  a  directory  in  which  the  shell  attempts  to  find  the  command 
(if  the  command  does  not  begin  with  /).  If  neither  -c  nor  -t  is  given,  the  shell  hashes  the  names  in 
these  directories  into  an  internal  table  so  that  an  exec  is  attempted  only  in  those  directories  where  the  com- 
mand might  possibly  reside.  This  greatly  speeds  command  location  when  a  large  number  of  directories  are 
present  in  the  search  path.  If  this  mechanism  has  been  turned  off  (via  unhash),  or  if  -c  or  -t  was 
given,  or  if  any  directory  component  of  path  does  not  begin  with  a  /,  the  shell  concatenates  the  directory 
name  and  the  given  command  name  to  forma  path  name  of  a  file  which  it  then  attempts  to  execute. 

Commands  placed  insideparenthesesarealwaysexecuted  inasubshell.  Thus 

(cd  ;  pwd) 

prints  the  home di rectory  then  returns  to  the  current  directory  upon  completion,  whereas: 
cd  ;  pwd 

remains  in  the  home  directory  upon  completion. 

When  commands  are  placed  inside  parentheses,  it  is  usually  to  prevent  chdir  from  affecting  the  current 
shell. 

If  the  file  has  execute  permissions  but  is  not  an  executable  binary  file,  it  is  assumed  to  be  a  script  file, 
which  is  a  file  of  data  for  an  interpreter  that  is  executed  as  a  separate  process. 

csh  first  attempts  to  load  and  execute  the  script  file  (see  exec(2)).  If  the  first  two  characters  of  the  script 
file  are  # ! ,  exec(2)  expects  an  interpreter  path  name  to  follow  and  attempts  to  execute  the  specified  inter- 
preter as  a  separate  process  to  read  the  entire  script  file. 

If  no  # !  interpreter  is  named,  and  there  is  an  alias  for  the  shell,  the  words  of  the  alias  are  inserted 
at  the  beginning  of  the  argument  list  to  form  the  shell  command.  The  first  word  of  the  alias  should  be  the 
full  path  name  of  the  command  to  be  used.  Note  that  this  is  a  special,  late-occurring  case  of  alias  substitu- 
tion, which  inserts  words  into  the  argument  list  without  modification. 

If  no  # !  interpreter  is  named  and  there  is  no  shell  alias,  but  the  first  character  of  the  file  is  #,  the 
interpreter  named  by  the  $shell  variable  is  executed  (note  that  this  normally  would  be 
/usr/bin/csh,  unless  the  user  has  reset  $shell).  If  $shell  is  not  set,  /usr/bin/csh  is  exe- 
cuted. 

If  no  !  #  interpreter  is  named,  and  there  is  no  shell  alias,  and  the  first  character  of  the  file  is  not  #, 
/usr/bin/sh  is  executed  to  interpret  the  script  file. 

History  Substitutions 

History  substitutions  enable  you  to  repeat  commands,  use  words  from  previous  commands  as  portions  of 
new  commands,  repeat  arguments  of  a  previous  command  in  the  current  command,  and  fix  spelling  or  typ- 
ing mistakes  in  an  earlier  command. 

History  substitutions  begin  with  an  exclamation  point  (!).  Substitutions  can  begin  anywhere  in  the  input 
stream,  but  cannot  be  nested.  The  exclamation  point  can  be  preceded  by  a  backslash  to  cancel  its  special 
meaning.  For  convenience,  an  exclamation  point  is  passed  to  the  parser  unchanged  when  it  is  followed  by  a 
blank,  tab,  newline,  equal  sign,  or  left  parenthesis.  Any  input  line  that  contains  history  substitution  is 
echoed  on  the  terminal  before  it  is  executed  for  verification. 

Commands  input  from  the  terminal  that  consist  of  one  or  more  words  are  saved  on  the  history  list.  The 
history  substitutions  reintroduce  sequences  of  words  from  these  saved  commands  into  the  input  stream. 
The  number  of  previous  commands  saved  is  controlled  by  the  history  variable.  The  previous  command 
is  always  saved,  regardless  of  its  value.  Commands  are  numbered  sequentially  from  1. 

You  can  refer  to  previous  events  by  event  number  (such  as  !  10  for  event  10),  relative  event  location  (such 
as  !-2  for  the  second  previous  event),  full  or  partial  command  name  (such  as  !d  for  the  last  event  using 
a  command  with  initial  character  d),  and  string  expression  (such  as  !  ?mic?  referring  to  an  event  contain- 
i  ng  the  characters  mic). 


Section  1-136 


-8- 


HP-UX  Release  Hi:  December  2000 


csh(l) 


csh(l) 


These  forms,  without  further  modification,  simply  reintroduce  the  words  of  the  specified  events,  each 
separated  by  a  singleblank.  As  a  special  case,  !!  is  a  re-do;  it  refers  to  the  previous  command. 

To  select  words  from  a  command,  use  a  colon  ( : )  and  a  designator  for  the  desired  words  after  the  event 
specification.  The  words  of  an  input  line  are  numbered  from  zero.  The  basic  word  designators  are: 

0     F  i  rst  word  (i  .e.,  the  command  name  itself). 

n      nth  word. 

A     First  argument.  (This  is  equivalent  to  1.) 
$     Last  word. 

a-b  Range  of  words  from  a  through  b.  Special  cases  are  -y,  an  abbreviation  for  "word  0  through 
word  y";  and  x-,  which  means  "word  x  up  to,  but  not  including,  word  $". 

*     Range  from  the  second  word  through  the  last  word. 

%     Used  with  a  search  sequence  to  substitutethe  immediately  preceding  matching  word. 

The  colon  separating  the  command  specification  from  the  word  designator  can  be  omitted  if  the  argument 
selector  begins  with  a  ",  $,  *,  -,  or  %. 

After  word  designator  can  be  followed  by  a  sequence  of  modifiers,  each  preceded  by  a  colon.  The  following 
modifiers  are  defined: 

h     Use  only  the  first  component  of  a  path  name  by  removing  all  following  components. 

r     Use  the  root  file  name  by  removing  any  trailing  suffix  (.xxx). 

e     Use  the  file  name's  trailing  suffix  ( .  xxx)  by  removing  the  root  name. 

s  /l/r 

substitutethe  value  of  r  for  the  value  I  in  the  indicated  command, 
t     Use  only  the  final  file  name  of  a  path  name  by  removing  all  leading  path  name  components. 
&     Repeat  the  previous  substitution, 
p     Print  the  new  command  but  do  not  execute  it. 
q     Quote  the  substituted  words,  preventing  further  substitutions, 
x     Likeq,  but  break  into  words  at  blanks,  tabs  and  newlines. 

g  Use  a  global  command  as  a  prefix  to  another  modifier  to  cause  the  specified  change  to  be  made 
globally.  All  words  in  the  command  are  changed,  one  change  per  word,  and  each  string  enclosed 
in  singlequotes  (' )  or  doublequotes  (  "  )  istreated  asa  singleword. 

Unless  preceded  by  a  g,  the  modification  is  applied  only  to  the  first  modifiable  word.  An  error  results  if  a 
substitution  is  attempted  and  cannot  be  completed  (i.e.,  if  you  ask  for  a  substitution  of  !  11  on  a  history 
buffer  containing  only  10  commands). 

The  left  hand  side  of  substitutions  are  strings;  not  regular  expressions  in  the  sense  of  hp-ux  editors.  Any 
character  can  be  used  as  the  delimiter  in  pi  ace  of  a  slash  (/).  Use  a  backslash  to  quote  a  delimiter  character 
if  it  is  used  in  the  I  or  r  string.  The  character  &  in  the  right-hand  side  is  replaced  by  the  text  from  the  left. 
A  \  also  quotes  &.  A  null  I  string  uses  the  previous  string  either  from  an  I  or  from  a  contextual  scan  string 
s  in  !  ?s?.  Thetrailing  delimiter  in  the  substitution  can  be  omitted  if  a  new-line  character  follows  immedi- 
ately, as  may  thetrailing  ?  in  a  contextual  scan. 

A  history  reference  can  be  given  without  an  event  specification  (as  in  !  $).  I  n  this  case,  the  reference  is  to 
the  previous  command  unless  a  previous  history  reference  occurred  on  the  same  line,  in  which  case  this 
form  repeats  the  previous  reference.  Thus 

!?foo?~  !$ 

gives  the  first  and  last  arguments  from  the  command  matching  ?foo?. 

A  special  abbreviation  of  a  history  reference  occurs  when  the  first  non-blank  character  of  an  input  line  is  a 
circumflex  f).  This  is  equivalent  to  !  :s",  providing  a  convenient  shorthand  for  substitutions  on  the  text  of 
the  previous  line.  Thus  "lb "lib  fixes  the  spelling  of  lib  in  the  previous  command. 

Finally,  a  history  substitution  can  be  enclosed  within  curly  braces  {  }  if  necessary  to  insulate  it  from  the 
characters  which  follow.  Thus,  after 
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Is  -Id  ~paul 
one  could  execute  !{l}atodo 

Is  -Id  "paula 
while  !  la  would  look  for  a  command  starting  with  la. 

Quoting  with  Single  and  Double  Quotes 

The  quotation  of  strings  by  single  quotes  (')  and  double  quotes  (  "  )  can  be  used  to  prevent  all  or  some  of  the 
remaining  substitutions.  Strings  enclosed  in  single  quotes  are  protected  from  any  further  interpretation. 
Strings  enclosed  in  double  quotes  are  still  variable-  and  command-expanded  as  described  below. 

I  n  both  cases  the  resulting  text  becomes  (all  or  part  of)  a  single  word.  Only  in  one  special  case  (see  Com- 
mand Substitution  below)  does  a  double-quoted  string  yield  parts  of  more  than  one  word;  single-quoted 
stri  ngs  never  do. 

Alias  Substitution 

csh  maintains  a  list  of  aliases  that  can  be  established,  displayed,  and  modified  by  the  alias  and 
unalias  commands.  After  a  command  line  is  scanned,  it  is  parsed  into  distinct  commands  and  the  first 
word  of  each  command,  left-to-right,  is  checked  to  see  if  it  has  an  alias.  If  it  does,  the  text  which  is  the 
alias  for  that  command  is  reread  with  the  history  mechanism  avail  able  as  if  that  command  was  the  previ- 
ous input  line.  The  resulting  words  replace  the  command  and  argument  list.  If  no  reference  is  made  to  the 
history  list,  the  argument  list  is  left  unchanged. 

Thus,  if  the  alias  for  Is  is  Is  -1,  the  command  Is  /usr  maps  to  Is  -1  /usr,  leaving  the  argu- 
ment list  undisturbed.  Similarly,  if  the  alias  for  lookup  was  grep  !~  /etc/passwd,  lookup 
bill  maps  to  grep  bill  /etc/passwd 

If  an  alias  is  found,  the  word  transformation  of  the  input  text  is  performed  and  the  aliasing  process  begins 
again  on  the  re-formed  input  line.  Looping  is  prevented  if  the  first  word  of  the  new  text  is  the  same  as  the 
old  by  flagging  it  to  prevent  further  aliasing.  Other  loops  are  detected  and  cause  an  error. 

Note  that  the  mechanism  allows  aliases  to  introduce  parser  metasyntax.  Thus: 

alias  print   'pr  \!*    |  lp' 

makes  a  command  that  uses  pr(l)  to  print  its  arguments  on  the  line  printer. 

Expressions 

Some  of  the  built-in  commands  take  expressions  in  which  the  operators  are  similar  to  those  of  C,  with  the 
same  precedence.  These  expressions  appear  in  the  @,  exit,  if,  and  while  commands.  The  following 
operators  are  avail  able  (shown  in  order  of  increasing  precedence): 

||   &&   |   "  &  ==  !=  =~   !"<=>=<>«»  +  -*/%   !   ~   (  ) 

The  following  list  shows  the  grouping  of  these  operators.  The  precedence  decreases  from  top  to  bottom  in 
the  list: 

*  /  % 
+  - 
«  » 
<=>=<> 
==   !=  =~    !  ~ 

The  operators  ==,  !=,  =~,  and  !  ~  compare  their  arguments  as  strings;  all  others  operate  on  numbers. 
Theoperators  =~  and  !  ~  are  similar  to  !=  and  ==,  except  that  the  right-hand  side  is  a  pattern  (contain- 
ing *s,  ?s,  and  instances  of  [...]  )  against  which  the  left  hand  operand  is  matched.  This  reduces  the  need 
for  use  of  the  switch  statement  in  shell  scripts  when  all  that  is  really  needed  is  pattern  matching. 

Strings  beginning  with  0  are  considered  octal  numbers.  Null  or  missing  arguments  are  considered  0.  The 
result  of  all  expressions  are  strings  that  represent  decimal  numbers.  It  is  important  to  note  that  no  two 
components  of  an  expression  can  appear  in  the  same  word.  These  components  should  be  surrounded  by 
spaces  except  when  adjacent  to  components  of  expressions  that  are  syntactically  significant  to  the  parser: 
-,  &,  I ,  <,  >,  (,  and  ) . 

Alsoavailablein  expressions  as  primitive  operands  are  command  executions  enclosed  in  curly  braces  ( {  } ) 
and  file  enquiries  of  the  form -I  filename,  where  I  is  one  of: 
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r 

read  access 

w 

write  access 

X 

execute  access 

e 

existence 

o 

ownership 

z 

zero  size 

f 

plain  file 

d 

directory 

The  specified  filename  is  command-  and  file-name  expanded  then  tested  to  see  if  it  has  the  specified  rela- 
tionship to  the  real  user.  If  the filedoes  not  exist  or  is  inaccessible,  all  inquiries  return  false(O).  Command 
executions  succeed,  returning  true,  if  the  command  exits  with  status  0;  otherwise  they  fail,  returning  false. 
If  more  detailed  status  information  is  required,  the  command  should  be  executed  outside  of  an  expression 
and  the  status  variableexamined. 

Control  of  the  Flow 

csh  contains  a  number  of  commands  that  can  be  used  to  regulate  the  flow  of  control  in  command  files 
(shell  scripts)  and  (in  limited  but  useful  ways)  from  terminal  input.  These  commands  all  operate  by  forcing 
the  shell  to  reread  or  skip  parts  of  its  input  and,  due  to  the  implementation,  restrict  the  placement  of  some 
of  the  commands. 

The  f oreach,  switch,  and  while  statements,  as  well  as  the  if-then-else  form  of  the  if  state- 
ment require  that  the  major  keywords  appear  in  a  single  simple  command  on  an  input  line  as  shown  below. 

If  the  shell's  input  is  not  seekable,  the  shell  buffers  input  whenever  a  loop  is  being  read  and  performs  seeks 
in  this  internal  buffer  to  accomplish  the  rereading  implied  by  the  loop.  (To  the  extent  that  this  allows, 
backward  gotos  succeed  on  non-seekable inputs.) 

Signal  Handling 

csh  normally  ignores  quit  signals.  J  obs  running  in  background  mode  are  immune  to  signals  generated 
from  the  keyboard,  including  hangups.  Other  signals  have  the  values  which  the  shell  inherited  from  its 
parent,  csh's  handling  of  interrupts  and  terminate  signals  in  shell  scripts  can  be  controlled  by  onintr. 
Login  shells  catch  the  terminate  signal;  otherwise  this  signal  is  passed  on  to  children  from  the  state  in  the 
shell's  parent.  I  n  no  case  are  interrupts  allowed  when  a  login  shell  is  reading  the  file  .  logout . 

Command  Line  Parsing 

csh  splitsinput  lines  into  words  at  blanks  and  tabs.  The  foil  owing  exceptions  (parser  metacharacters)  are 
considered  separate  words: 


& 

ampersand; 

1 

vertical  bar; 

1 

semicolon; 

< 

less-than  sign; 

> 

greater-than  sign; 

( 

left  parenthesis; 

) 

right  parenthesis; 

&& 

double  ampersand; 

1 1 

double  vertical  bar; 

« 

double  less-than  sign; 

» 

double  greater-than  sign; 

# 

comment  delimiter 

The  backslash  (\)  removes  the  special  meaning  of  these  parser  metacharacters.  A  parser  metacharacter 
preceded  by  a  backslash  is  interpreted  as  its  ASCII  value.  A  newline  character  (ASCII  10)  preceded  by  a 
backslash  is  equivalent  to  a  blank. 

Strings  enclosed  in  singleor  double  quotes  form  parts  of  a  word.  Metacharacters  in  these  stri ngs,  including 
blanks  and  tabs,  do  not  form  separate  words.  Within  pairs  of  backslashes  or  quotes,  a  newline  preceded  by 
a  backslash  gives  a  true  newline  character. 

When  csh's  input  is  not  a  terminal,  the  #  character  introduces  a  comment  terminated  by  a  newline. 

CSH  VARIABLES 

csh  maintains  a  set  of  variables.  Each  variable  has  a  value  equal  to  zero  or  more  strings  (words).  Vari- 
ables have  names  consisting  of  up  to  80  letters  and  digits  starting  with  a  letter.  The  underscore  character 
is  considered  a  letter.  The  value  of  a  variable  may  be  displayed  and  changed  by  using  the  set  and 
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unset  commands.  Some  of  the  variables  are  Boolean,  that  is,  the  shell  does  not  care  what  their  value  is, 
only  whether  they  are  set  or  not. 

Some  operations  treat  variables  numerically.  The  at  sign  (@)  command  permits  numeric  calculations  to  be 
performed  and  the  result  assigned  to  a  variable.  The  null  string  is  considered  to  be  zero,  and  any  subse- 
quent words  of  multi-word  values  are  ignored. 

After  the  input  line  is  aliased  and  parsed,  and  before  each  command  is  executed,  variable  expansion  is  per- 
formed keyed  by  the  dollar  sign  ($)character .  Variable  expansion  can  be  prevented  by  preceding  the 
dollar  sign  with  a  backslash  character  (\)  except  within  double  quotes  (")  where  substitution  always 
occurs.  Variables  are  never  expanded  if  enclosed  in  single  quotes.  Strings  quoted  by  single  quotes  are 
interpreted  later  (see  Command  Substitution)  so  variable  substitution  does  not  occur  there  until  later,  if  at 
all.  A  dollar  sign  is  passed  unchanged  if  followed  by  a  blank,  tab,  or  end-of-line. 

I  nput/output  redirections  are  recognized  before  variable  expansion,  and  are  variable  expanded  separately. 
Otherwise,  the  command  name  and  entire  argument  list  are  expanded  together. 

Unless  enclosed  in  double  quotes  or  given  the  :q  modifier,  the  results  of  variable  substitution  may  eventu- 
ally be  command  and  file  name  substituted.  Within  double  quotes,  a  variable  whose  value  consists  of  multi- 
plewords  expands  toa  portion  of  a  singleword,  with  the  words  of  the  variable's  value  separated  by  blanks. 
When  the  :q  modifier  is  applied  toa  substitution,  the  variable  expands  to  multiple  words  with  each  word 
separated  by  a  blank  and  quoted  to  prevent  later  command  or  file  name  substitution. 

The  following  metasequences  are  provided  for  introducing  variable  values  into  the  shell  input.  Except  as 
noted,  it  is  an  error  to  reference  a  variablethat  is  not  set. 

$variable_name 
${variable_name} 

When  interpreted,  this  sequence  is  replaced  by  the  words  of  the  value  of  the  variable 
variablename,  each  separated  by  a  blank.  Braces  insulate  variablename  from  subsequent 
characters  that  would  otherwise  be  interpreted  to  be  part  of  the  variablename  itself. 
If  variable  name  is  not  a  csh  variable,  but  is  set  in  the  environment,  that  value  is  used. 
Non-csh  variables  cannot  be  modified  as  shown  below. 

$  va  r  i  a  bl  e  n  a  mefsel  ector  ] 

${  variablenamef  selector] } 

This  modification  selects  only  some  of  the  words  from  the  value  of  variable  name.  The 
selector  is  subjected  to  variable  substitution,  and  can  consist  of  a  single  number  or  two 
numbers  separated  by  a  dash.  The  first  word  of  a  variable's  value  is  numbered  1.  If  the  first 
number  of  a  range  is  omitted  it  defaults  to  1.  If  the  last  member  of  a  range  is  omitted  it 
defaults  to  the  total  number  of  words  in  the  variable  ($#variable_name).  An  asterisk  meta- 
character used  as  a  selector  selects  all  words. 

$#variable_name 
${#variable_name} 

This  form  gives  the  number  of  words  in  the  variable,  and  is  useful  for  forms  using  a  [selec- 
tor] option. 

$0         This  form  substitutes  the  name  of  the  file  from  which  command  input  is  being  read.  An 
error  occurs  if  the  file  name  is  not  known. 

$number 
${  number} 

This  form  is  equivalent  to  an  indexed  selection  from  the  variable  argv  ($argv[  number] ). 

$*         This  is  equivalent  to  selecting  all  of  argv  ($argv[*]  ). 

The  modifiers  :h,  :t,  :r,  :q,  and  :x  can  be  applied  to  the  substitutions  above,  as  can  CR  :gh  ,  CR  :gt  , 
and  CR  :gr  .  If  curly  braces  ({  })  appear  in  the  command  form,  the  modifiers  must  appear  within  the 
braces.  Thecurrent  implementation  allows  only  one  :  modifier  on  each  $d  expansion. 

Thefollowing  substitutions  cannot  be  modified  with  :  modifiers: 

$?variable_name 
${?variable_name} 

Substitutes  the  string  1  if  variablename  is  set,  Oifitisnot. 

$?0       Substitutes  1  if  the  current  input  file  name  is  known,  Oifitisnot. 

$$         Substitutes  the  (decimal)  process  number  of  the  (parent)  shell. 


Section  1-140 


-12- 


HP-UX  Release  Hi:  December  2000 


csh(l) 


csh(l) 


$<         Substitutes  a  line  from  the  standard  input,  with  no  further  interpretation  thereafter.  It  can 
be  used  to  read  from  the  keyboard  in  a  shell  script. 

Pre-Defined  and  Environment  Variables 

The  following  variables  have  special  meaning  to  the  shell.  Of  these  autologout ,  argv,  cwd,  home, 
path,  prompt,  shell,  and  status  are  always  set  by  the  shell.  Except  for  cwd  and  status,  this 
setting  occurs  only  at  initialization  (initial  execution  of  csh).  These  variables  are  not  modified  unless 
modified  explicitly  by  the  user. 

csh  copies  the  hp-ux  environment  variable  user  into  the  shell  variable  user,  the  environment  variable 
TERM  into  term,  the  environment  variable  HOME  into  home,  and  PATH  into  path,  csh  copies  these 
values  back  into  the  environment  whenever  the  csh  variables  are  reset. 

I  n  a  windowed  environment,  if  csh  detects  that  the  window  has  changed  size,  csh  sets  the  environment 
variables  LINES  and  COLUMNS  to  match  the  new  window  size. 


argv 

cdpath 

cwd 

echo 

history 

home 

ignoreeof 
mail 


noclobber 


noglob 


nonomatch 


This  variable  is  set  to  the  arguments  of  the  csh  command  statement.  It  is  from  this 
variable  that  positional  parameters  are  substituted;  i.e.,  $1  is  replaced  by 
$argv[l]  ,  etc 

This  variable  gives  a  list  of  alternate  directories  searched  to  find  subdirectories  in 
chdir  commands. 

This  variable  contains  the  absolute  path  name  of  the  current  working  directory. 
Whenever  changing  directories  (using  cd),  this  variableis  updated. 

This  variable  is  set  by  the  -x  command  line  option.  If  set,  all  built-in  commands  and 
their  arguments  are  echoed  to  the  standard  output  device  just  before  being  executed. 
Built-in  commands  are  echoed  before  command  and  file  name  substitution,  since  these 
substitutions  are  then  done  selectively.  For  non-built-in  commands,  all  expansions 
occur  before  echoing. 

This  variable  is  used  to  create  the  command  history  buffer  and  to  set  its  size.  If  this 
variable  is  not  set,  no  command  history  is  maintained  and  history  substitutions  cannot 
be  made.  Very  large  values  of  history  can  cause  shell  memory  overflow.  Values  of 
10  or  20  are  normal.  All  commands,  executable  or  not,  are  saved  in  the  command  his- 
tory buffer. 

This  variable  contains  the  absolute  path  name  to  your  home  directory.  The  variable 
home  is  initialized  from  the  hp-ux  environment.  File  name  expansion  of  tilde  (") 
refers  to  this  variable. 

If  set,  csh  ignores  end-of-file  characters  from  input  devices  that  are  terminals, 
csh  exits  normally  when  it  encounters  the  end-of-file  condition  (CTRL-D  typed  as  the 
first  character  on  a  command  line).  Setting  ignoreeof  prevents  the  current  shell  from 
being  killed  by  an  accidental  (CTRL-D.  However,  to  prevent  an  infinite  loop  of  EOF 
input,  csh  terminates  if  it  receives  26  consecutive eofs. 

This  variable  contains  a  list  of  the  files  where  csh  checks  for  your  mail,  csh 
periodically  (default  is  10  minutes)  checks  this  variable  before  producing  a  prompt 
upon  command  completion.  If  the  variable  contains  a  file  name  that  has  been 
modified  since  the  last  check  (resulting  from  mail  being  put  in  the  file),  csh  prints 
You  have  new  mail. 

If  the  first  word  of  the  value  of  mail  is  numeric,  that  number  specifies  a  different 
mail  checking  interval  in  seconds. 

If  multiple  mail  files  are  specified,  the  shell  says  New  mail  in  file  name,  where 
file  name  is  the  file  containing  the  mail. 

This  variable  places  restrictions  on  output  redirection  to  ensure  that  files  are  not 
accidentally  destroyed,  and  that  commands  using  append  redirection  (»)  refer  to 
existing  files. 

If  set,  file  name  expansion  is  inhibited.  This  is  most  useful  in  shell  scripts  that  are  not 
dealing  with  file  names,  or  after  a  list  of  file  names  has  been  obtained  and  further 
expansions  are  not  desirable. 

If  set,  it  is  no  longer  an  error  for  a  file  name  expansion  to  not  match  any  existing  files. 
If  there  is  no  match,  the  primitive  pattern  is  returned.  It  is  still  an  error  for  the 
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primitive  pattern  to  be  malformed.  For  example,  'echo  ['  still  gives  an  error. 

notify  If  set,  csh  notifies  you  immediately  (through  your  standard  output  device)  of  back- 
ground job  completions.  The  default  is  unset  (indicate  job  completions  just  before 
printing  a  prompt). 

path  Each  word  of  the  path  variable  specifies  a  directory  in  which  commands  are  to  be 

sought  for  execution.  A  null  word  specifies  your  current  working  directory.  If  there  is 
no  path  variable,  only  full  path  names  can  be  executed.  When  path  is  not  set  and 
when  users  do  not  specify  full  path  names,  csh  searches  for  the  command  through 
the  directories  .  (current  directory)  and  /usr/bin.  A  csh  which  is  given  neither 
the  -c  nor  the  -t  option  normally  hashes  the  contents  of  the  directories  in  the 
path  variable  after  reading  .cshrc,  and  each  time  the  path  variable  is  reset.  If 
new  commands  are  added  to  these  directories  while  the  shell  is  active,  it  is  necessary 
to  execute  rehash  for  csh  to  access  these  new  commands. 

prompt  This  variable  lets  you  select  your  own  prompt  character  string.  The  prompt  is  printed 
before  each  command  is  read  from  an  interactive  terminal  input.  If  a  !  appears  in 
the  string,  it  is  replaced  by  the  current  command  history  buffer  event  number  unless  a 
preceding  \  is  given.  The  default  prompt  is  the  percent  sign  (%)  for  users  and  the  # 
character  for  the  super-user. 

savehist  The  number  of  lines  from  the  history  list  that  are  saved  in  "/  .history  when  the 
user  logs  out.  Large  values  for  savehist  slow  down  the  csh  during  startup. 

shell  This  variable  contains  the  name  of  the  file  in  which  the  csh  program  resides.  This 

variable  is  used  in  forking  shells  to  interpret  files  that  have  their  execute  bits  set  but 
which  are  not  executable  by  the  system.  (See  the  description  of  Non-Built-in  Com- 
mand Execution). 

status  This  variable  contains  the  status  value  returned  by  the  last  command.  If  the  com- 
mand terminated  abnormally,  0200  is  added  to  the  status  variable's  value.  Built-in 
commands  which  terminated  abnormally  return  exit  status  1,  and  all  other  built-in 
commands  set  status  to  0. 

time  This  variable  contains  a  numeric  value  that  controls  the  automatic  timing  of  com- 

mands. If  set,  csh  prints,  for  any  command  taking  more  than  the  specified  number 
of  cpu  seconds,  a  line  of  information  to  the  standard  output  device  giving  user,  system, 
and  real  execution  times  plus  a  utilization  percentage.  The  utilization  percentage  is 
the  ratio  of  user  plus  system  times  to  real  time.  This  message  is  printed  after  the 
command  finishes  execution. 

verbose  This  variable  is  set  by  the  -v  command  line  option.  If  set,  the  words  of  each  com- 
mand are  printed  on  the  standard  output  device  after  history  substitutions  have  been 
made. 


Command  and  File  name  Substitution 

The  remaining  substitutions,  command  and  file  name  substitution,  are  applied  selectively  to  the  arguments 
of  built-in  commands.  This  means  that  portions  of  expressions  that  are  not  evaluated  are  not  subjected  to 
these  expansions.  For  commands  which  are  not  internal  to  the  shell,  the  command  name  is  substituted 
separately  from  the  argument  list.  This  occurs  very  late,  after  input-output  redirection  is  performed,  and 
in  a  child  of  the  main  shell. 


Command  Substitution 

Command  substitution  is  indicated  by  a  command  enclosed  in  grave  accents  C  ■■■")■  The  output  from  such 
a  command  is  normally  broken  into  separate  words  at  blanks,  tabs  and  newlines,  with  null  words  being  dis- 
carded; this  text  then  replacing  the  original  string.  Within  double  quotes,  only  newlines  force  new  words; 
blanks  and  tabs  are  preserved. 

I  n  any  case,  the  single  final  newlinedoes  not  force  a  new  word.  Note  that  it  is  thus  possible  for  a  command 
substitution  to  yield  only  part  of  a  word,  even  if  the  command  outputs  a  complete  line. 

File  name  Substitution 

Each  command  word  is  processed  as  a  pattern  for  file  name  substitution,  also  known  as  globbing,  and 
replaced  with  a  sorted  list  of  file  names  which  match  the  pattern.  The  form  of  the  patterns  is  the  Pattern 
Matching  Notation  defined  by  regexp(5)  with  the  following  exceptions: 
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•  Non-matching  lists  in  bracket  expressions  are  not  supported. 

•  I  n  a  list  of  words  specifying  file  name  substitution  it  is  an  error  for  no  pattern  to  match  an  existing 
file  name,  but  it  is  not  required  for  each  pattern  to  match. 

•  The  metanotation  a{b,c,d]e  is  a  shorthand  for  "abe  ace  ade".  Left  to  right  order  is  preserved,  with 
results  of  matches  being  sorted  separately  at  a  low  level  to  preserve  this  order.  This  construct  may 
be  nested.  Thus: 

~source/sl/ {oldls, Is} .c 

expands  to 

/home/ source/ sl/oldls . c  /home/source/sl/ls . c 

whether  or  not  these  files  exist,  without  any  chance  of  error  if  the  home  directory  for  source  is 
/home/source.  Similarly, 

. . / { memo , *box } 

might  expand  to 

. ./memo   . ./box   . ./mbox 

(Note  that  memo  was  not  sorted  with  the  results  of  matching  *box.)  As  a  special  case,  {,  },  and 
{  }  are  passed  undisturbed. 


Input/Output 

The  standard  input  and  standard  output  of  a  command  can  be  redirected  with  the  foil  owing  syntax: 


<  name 
«  word 


>  name 
>!  name 
>&  name 
>& !  name 


Open  file  name  (which  is  first  variable,  command  and  file  name  expanded)  as  the  stan- 
dard input. 

Read  the  shell  input  up  to  a  line  which  is  identical  to  word,  word  is  not  subjected  to 
variable,  file  name  or  command  substitution,  and  each  input  line  is  compared  to  word 
before  any  substitutions  are  done  on  this  input  line.  Unless  a  quoting  \,  ' ,  or 
appears  in  word,  variable  and  command  substitution  is  performed  on  the  intervening 
lines,  allowing  \  to  quote  $,  \  and  \  Commands  which  are  substituted  have  all 
blanks,  tabs,  and  newlines  preserved,  except  for  the  final  newline  which  is  dropped. 
The  resultant  text  is  placed  in  an  anonymous  temporary  file  which  is  given  to  the  com- 
mand as  standard  input. 


The  file  name  is  used  as  standard  output.  If  the  file  does  not  exist,  it  is  created;  if  the 
file  exists,  it  is  truncated,  and  its  previous  contents  are  lost. 

If  the  variable  noclobber  isset,  thefilemust  not  exist  or  bea  character  special  file 
(e.g.,  a  terminal  or  /dev/null)  or  an  error  results.  This  helps  prevent  accidental 
destruction  of  files.  In  this  case  the  exclamation  point  (!)  forms  can  be  used  to 
suppress  this  check. 

The  forms  involving  the  ampersand  character  (&)  route  the  standard  error  into  the 
specified  file  as  well  as  the  standard  output,  name  is  expanded  in  the  same  way  as  < 
input  file  names  are. 

»  name 
»&  name 
»!  name 

»&!  name  Uses  file  nameas  standard  output  the  same  as  >,  but  appends  output  to  the  end  of  the 
file.  If  the  variable  noclobber  is  set,  it  is  an  error  for  the  file  not  to  exist  unless 
oneofthe  !  forms  is  given.  Otherwise,  it  is  similar  to  >. 

A  command  receives  the  environment  in  which  the  shell  was  invoked  as  modified  by  the  input-output 
parameters  and  the  presence  of  the  command  in  a  pipeline.  Thus,  unlike  some  previous  shells,  commands 
executed  from  a  shell  script  have  no  access  to  the  text  of  the  commands  by  default;  rather  they  receive  the 
original  standard  input  of  the  shell.  The  «  mechanism  should  be  used  to  present  inline  data.  This  per- 
mits shell  scripts  to  function  as  components  of  pipelines  and  allows  the  shell  to  block-read  its  input. 
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Diagnostic  output  can  be  directed  through  a  pipe  with  the  standard  output.  Simply  use  the  form  |& 
rather  than  |  by  itself. 

CSH  UTILITIES 

File  Name  Completion 

I  n  typing  file  names  as  arguments  to  commands,  it  is  no  longer  necessary  to  type  a  complete  name,  only  a 
unique  abbreviation  is  necessary.  When  you  want  the  system  to  try  to  match  your  abbreviation,  press  the 
ESC  key.  The  system  then  completes  the  file  name  for  you,  echoing  the  full  name  on  your  terminal.  If  the 
abbreviation  does  not  match  an  availablefile  name,  the  terminal's  bell  is  sounded.  The  file  name  may  be 
partially  completed  if  the  prefix  matches  several  longer  file  names.  I  n  this  case,  the  name  is  extended  up  to 
the  ambiguous  deviation,  and  the  bell  issounded. 

File  name  completion  works  equally  well  when  other  directories  are  addressed.  I  n  addition,  the  tilde  (") 
convention  for  home  directories  is  understood  in  this  context. 

Viewing  a  File  or  Directory  List 

At  any  point  in  typing  a  command,  you  can  request  "what  files  are  available"  or  "what  files  match  my 
current  specification".  Thus,  when  you  have  typed: 

%  cd  ~speech/data/bench/f ritz/ 

you  may  wish  to  know  what  files  or  subdirectories  exist  (in  ~speech/data/bench/f ritz),  without 
aborting  the  command  you  are  typing.  Typing  CTRL-D  atthispoint  lists  the  files  available.  Files  are  listed 
in  multicolumn  format,  sorted  by  column.  Directories  and  executable  files  are  identified  by  a  trailing  / 
and  *,  respectively.  Once  printed,  the  command  is  re-echoed  for  you  to  complete.  Additionally,  you  may 
want  to  know  which  files  match  a  prefix,  the  current  file  specification  so  far.  If  you  had  typed: 

%  cd  ~speech/data/bench/f r 

followed  by  a  CTRL-D,  all  files  and  subdirectories  whose  prefix  was  fr  in  the  directory 
"speech/data/bench  would  be  printed.  Notice  that  the  example  before  was  simply  a  degenerate  case 
of  this  with  a  null  trailing  file  name.  (The  null  string  is  a  prefix  of  all  strings.)  Notice  also  that  a  trailing 
slash  is  required  to  pass  to  a  new  sub-directory  for  both  file  name  completion  and  listing.  Note  that  the 
degenerate  case 

%  ~~D 

prints  a  full  list  of  login  names  on  the  current  system. 

Command  Name  Recognition 

Command  name  recognition  and  completion  works  in  the  same  manner  as  file  name  recognition  and  com- 
pletion above.  The  current  value  of  the  environment  variable  PATH  is  used  in  searching  for  the  command. 
For  example 

%  newa  [Escape] 

might  expand  to 

%  newaliases 

Also, 

%  new   [Control] - [D] 

lists  all  commands  (along  PATH)  that  begin  with  new.  As  an  option,  if  the  shell  variable  listpathnum 
is  set,  a  number  indicating  the  index  in  PATH  is  printed  next  to  each  command  on  a  [Control  ]-[D]  listing. 

Autologout 

A  new  shell  variable  has  been  added  called  autologout.  If  the  terminal  remains  idle  (no  character 
input)  at  the  shell's  top  level  for  a  number  of  minutes  greater  than  the  value  assigned  to  autologout, 
you  are  automatically  logged  off.  The  autologout  feature  is  temporarily  disabled  while  a  command  is 
executing.  The  initial  value  of  autologout  is  60.  If  unset  or  set  to  0,  autologout  is  entirely  dis- 
abled. 

Command  Line  Control 

A  ~R  re-prints  the  current  command  line;  ~W  erases  the  last  word  entered  on  the  current  command  line. 
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Sanity 

C  shell  restores  your  terminal  to  a  sane  mode  if  it  appears  to  return  from  some  command  in  raw,  cbreak,  or 
noecho  mode. 

Saving  Your  History  Buffer 

csh  hastheabilitytosaveyour  history  list  between  login  sessions.  If  the  shell  variable  savehist  isset 
to  a  number,  that  number  of  command  events  from  your  history  list  is  saved.  For  example,  placing  the  line 

set  history=10  savehist=10 

in  your  .cshrc  file  maintains  a  history  buffer  of  length  10  and  saves  the  entire  list  when  you  logout. 
When  you  log  back  in,  the  entire  buffer  is  restored.  The  commands  are  saved  in  the  file  .history  in 
your  login  directory. 

EXTERNAL  INFLUENCES 
Environment  Variables 

lccollate  determines  the  collating  sequence  used  in  evaluating  pattern  matching  notation  for  file  name 
substitution. 

lcctype  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification  of 
characters  as  letters,  and  the  characters  matched  by  character  class  expressions  in  pattern  matching  nota- 
tion. 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  lc  collate  or  lc  ctype  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of 
LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  con- 
tains an  invalid  setting,  csh  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

WARNINGS 

The  .  cshrc  file  should  be  structured  such  that  it  cannot  generate  any  output  on  standard  output  or  stan- 
dard error,  including  occasions  when  it  is  invoked  without  an  affiliated  terminal,  rcp(l)  causes  .cshrc  to 
be  sourced,  and  any  output  generated  by  this  file,  even  to  standard  error  causes  problems.  Commands  such 
as  stty(l)  should  be  placed  in  .  login,  not  in  .  cshrc,  so  that  their  output  cannot  affect  rcp(l). 

csh  has  certain  limitations.  Words  or  environment  variables  can  be  no  longer  than  10240  characters.  The 
system  limits  argument  lists  to  10240  characters.  The  number  of  arguments  to  a  command  which  involves 
file  name  expansion  is  limited  to  one-sixth  the  number  of  characters  allowed  in  an  argument  list.  Com- 
mand substitutions  may  substitute  no  more  characters  than  are  allowed  in  an  argument  list. 

To  detect  looping,  the  shell  restricts  the  number  of  alias  substitutions  on  a  single  line  to  20. 

When  a  command  is  restarted  from  a  stop,  csh  prints  the  directory  it  started  in  if  it  is  different  from  the 
current  directory;  this  can  be  misleading  (i.e.,  wrong)  because  thejob  may  have  changed  directories  inter- 
nally. 

Shell  built-in  functions  are  not  stoppable/restartable.  Command  sequences  of  the  form  a  ;  b  ;  care 
also  not  handled  gracefully  when  stopping  is  attempted.  If  you  interrupt  b,  the  shell  then  immediately  exe- 
cutes c.  This  is  especially  noticeable  if  this  expansion  results  from  an  alias.  It  suffices  to  place  the 
sequenceof  commands  in  parenthesesto  force  it  intoa  subshell;  i.e.,  (  a  ;  b  ;  c  ). 

Because  of  the  signal  handling  required  by  csh,  interrupts  are  disabled  just  before  a  command  is  executed, 
and  restored  as  the  command  begins  execution.  There  may  be  a  few  seconds  delay  between  when  a  com- 
mand is  given  and  when  interrupts  are  recognized. 

Control  over  tty  output  after  processes  are  started  is  primitive;  perhaps  this  will  inspire  someone  to  work 
on  a  good  virtual  terminal  interface.  In  a  virtual  terminal  interface  much  more  interesting  things  could  be 
done  with  output  control. 

Alias  substitution  is  most  often  used  to  clumsily  simulate  shell  procedures;  shell  procedures  should  be  pro- 
vided rather  than  aliases. 

Commands  within  loops,  prompted  for  by  ?,  are  not  placed  in  the  history  list.  Control  structure  should  be 
parsed  rather  than  being  recognized  as  built-in  commands.  This  would  allow  control  commands  to  be 
placed  anywhere,  to  be  combined  with  | ,  and  to  be  used  with  &  and  ;  metasyntax. 
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It  should  be  possible  to  use  the  :  modifiers  on  the  output  of  command  substitutions.  All  and  more  than 
one  :  modifier  should  be  allowed  on  $  substitutions. 

Terminal  type  is  examined  only  the  first  time  you  attempt  recognition. 

To  list  all  commands  on  the  system  along  PATH,  enter  [Space]-[Ctrl]-[D]. 

Thecsh  metasequence  !  ~  does  not  work. 

In  an  international  environment,  character  ordering  is  determined  by  the  setting  of  lccollate,  rather 
than  by  the  binary  ordering  of  character  values  in  the  machine  collating  sequence.  This  brings  with  it  cer- 
tain attendant  dangers,  particularly  when  using  range  expressions  in  file  name  generation  patterns.  For 
example,  the  command, 

rm   [a-z] * 

might  be  expected  to  match  all  file  names  beginning  with  a  lowercase  alphabetic  character.  However,  if 
dictionary  ordering  is  specified  by  lc  collate,  it  would  also  match  file  names  beginning  with  an  uppercase 
character  (as  well  as  those  beginning  with  accented  letters).  Conversely,  it  would  fail  to  match  letters  col- 
lated after  z  in  languages  such  as  Norwegian. 

The  correct  (and  safe)  way  to  match  specific  character  classes  in  an  international  environment  is  to  use  a 
pattern  of  the  form: 

rm   [ [ : lower : ] ] * 

This  uses  LC_CTYPE  to  determine  character  classes  and  works  predictably  for  all  supported  languages 
and  codesets.  For  shell  scripts  produced  on  non-internationalized  systems  (or  without  consideration  for  the 
above  dangers),  it  is  recommended  that  they  be  executed  in  a  non-NLS  environment.  This  requires  that 
LANG,  LC_COLLATE ,  etc.,  be  set  to  "C"  or  not  set  at  all . 

csh  implements  command  substitution  by  creating  a  pipe  between  itself  and  the  command.  If  the  root  file 
system  is  full,  the  substituted  command  cannot  write  to  the  pipe.  As  a  result,  the  shell  receives  no  input 
from  the  command,  and  the  result  of  the  substitution  is  null.  I  n  particular,  using  command  substitution  for 
variable  assignment  under  such  circumstances  results  in  the  variable  being  silently  assigned  a  null  value. 

Relative  path  changes  (such  as  cd  .  . ),  when  in  a  symbolically  linked  directory,  cause  csh's  knowledge  of 
the  working  directory  to  be  along  the  symbolic  path  instead  of  the  physical  path. 

Prior  to  hp-ux  Release  9.0,  csh,  when  getting  its  input  from  a  file,  would  exit  immediately  if  unable  to  exe- 
cute a  command  (such  as  if  it  was  unable  to  find  the  command).  Beginning  at  Release  9.0,  csh  continues 
on  and  attempts  to  execute  the  remaining  commands  in  the  file.  However,  if  the  old  behavior  is  desired  for 
compatibility  purposes,  set  the  environment  variable  exitonerr  to  1. 

AUTHOR 

csh  was  developed  by  the  University  of  California,  Berkeley  and  HP. 
FILES 

"/  .  cshrc  A  csh  script  sourced  (executed)  at  the  beginning  of  execution  by  each  shell.  See 

WARNINGS 

"/.login  A  csh  script  sourced  (executed)  by  login  shell,  after  .  cshrc  at  login. 

"/  .logout  A  csh  script  sourced  (executed)  by  login  shell,  at  logout, 

/etc/passwd  Source  of  home  directories  for  "name, 

/usr/bin/sh  Standard  shell,  for  shell  scripts  not  starting  with  a  #. 

/etc/csh .  login       A  csh  script  sourced  (executed)  before  "/  .  cshrc  and  "/  .  login  when  start- 
ing a  csh  login  (analogousto  /etc/profile  in  the  Bourne  shell). 

/tmp/sh*  Temporary  file  for  «. 

SEE  ALSO 

cd(l),  echo(l),  kill(l),  nice(l),  sh(l),  umask(l),  access(2),  exec(2),  fork(2),  pipe(2),  umask(2),  wait(2),  tty(7), 
a.out(4),  environ(5),  lang(5),  regexp(5). 

C  Shell  tutorial  in  Shells  Users  Guide. 
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NAME 

csplit  -  context  split 

SYNOPSIS 

csplit  [-s]  [-k]  [-f  prefix]  [-n  number]  file  argl  [...argn] 
DESCRIPTION 

csplit  reads  file,  separates  it  into  n+1  sections  as  defined  by  the  arguments  argl  ...  argn,  and  places 
the  results  in  separate  files.  The  maximum  number  of  arguments  (argl  through  argn)  allowed  is  99  unless 
the-n  number  option  is  used  to  allow  for  more  output  file  names.  If  the -f  prefix  option  is  specified,  the 
resulting  filenames  are  prefixOO  through  prefixNN  where  NN  is  the  two-digit  value  of  n  using  a  leading 
zero  if  n  is  less  than  10.  If  the  -f  prefix  option  is  not  specified,  the  default  filenames  xxOO  through 
xxNN  are  used,  file  is  divided  as  follows: 


Default 
Filename 

xxOO 
xxOl 


Prefixed 
Filename 

prefixOO 

prefixOl 


Contents 

From  start  of  file  up  to  (but  not  including)  the  line  refer- 
enced by  argl. 

From  the  line  referenced  by  argl  up  to  the  line  referenced 
by  arg2. 


xxNN        prefixNN      From  the  line  referenced  by  argn  to  end  of  file. 
If  the  file  argument  is  -,  standard  input  is  used, 
csplit  supports  the  Basic  Regular  Expression  syntax  (see  regexp(5)). 

Options 

csplit  recognizes  the  following  options: 

-s  Suppress  printing  of  all  character  counts  (csplit  normally  prints  the  character 

counts  for  each  file  created). 

-k  Leave  previously  created  files  intact  (csplit  normally  removes  created  files  if  an 

error  occurs). 

-f  prefix        Name  created  files  prefixOO  through  prefixNN  (default  is  xxOO  through  xxNN. 

-n  number  The  output  file  name  suffix  will  use  number  digits  instead  of  the  default  2.  This 
allows  creation  of  more  than  100  output  files. 

Arguments  (argl  through  argn)  to  csplit  can  beany  combination  of  the  following: 

/regexp/  Create  a  file  containing  the  section  from  the  current  line  up  to  (but  not  including)  the 
line  matching  the  regular  expression  regexp.  The  new  current  line  becomes  the  line 
matching  regexp. 

/regexp/+n 

/regexp/-n  Create  a  file  containing  the  section  from  the  current  line  up  to  (but  not  including)  the 
nth  before  (-n)  or  after  (+n)  the  line  matching  the  regular  expression  regexp.  (e.g., 
/Page/-5).  The  new  current  line  becomes  the  line  matching  regexp±n  lines. 

%regexp%        equivalent  to /regexp/,  except  that  no  file  is  created  for  the  section. 

linenumber  Create  a  file  from  the  current  line  up  to  (but  not  including)  linenumber.  The  new 
current  line  becomes  line  number. 

{num}  Repeat  argument.  This  argument  can  follow  any  of  the  above  argument  forms.  If  it 

follows  a  regexp  argument,  that  argument  is  applied  num  more  times.  If  it  follows 
line  number,  the  file  is  split  every  line  number  lines  for  num  times  from  that  point 
until  end-of-file  is  reached  or  num  expires. 

{* }  Repeats  previous  operand  as  many  times  as  necessary  to  finish  input. 

Enclosein  appropriate  quotes  all  regexp  arguments  containing  blanks  or  other  characters  meaningful  to  the 
shell.  Regular  expressions  must  not  contain  embedded  new-lines,    csplit  does  not  alter  or  remove  the 
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original  file;  it  is  the  user's  responsibility  to  remove  it  when  appropriate. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  regular  expressions. 

LC_CTYPE  determines  the  characters  matched  by  character  class  expressions  in  regular  expressions. 
LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_COLLATE  or  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the 
empty  string,  the  value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is 
not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any 
internationalization  variable  contains  an  invalid  setting,  csplit  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Messages  are  self  explanatory  except  for: 

arg  -  out  of  range 

which  means  that  the  given  argument  did  not  reference  a  line  between  the  current  position  and  the  end  of 
the  file.  This  warning  also  occurs  if  the  file  is  exhausted  before  the  repeat  count  is. 

EXAMPLES 

Create  four  files,  cobolOO  through  cobol03.  After  editing  the  "split"  files,  recombi ne  them  back  into 
the  original  file,  destroying  its  previous  contents. 

csplit  -f  cobol  file   '/procedure  division/'    /par5./  /parl6./ 

Perform  editing  operations 

cat  cobol0[0-3]    >  file 

Split  a  file  at  every  100  lines,  up  to  10,000  lines  (100  files).  The  -k  option  causes  the  created  files  to  be 
retained  if  there  are  fewer  than  10,000  lines  (an  error  message  is  still  printed). 

csplit  -k  file  100  '{99}' 

Assuming  that  prog.c  follows  the  normal  C  coding  convention  of  terminating  routines  with  a  }  at  the 
beginning  of  the  line,  create  a  file  containing  each  separatee  routine  (up  to  21)  in  prog.  c. 

csplit  -k  prog.c   '%main(%'    '/~}/+l'  '{20}' 

SEE  ALSO 

sh(l),  split(l),  environ(5),  lang(5),  regexp(5). 

STANDARDS  CONFORMANCE 

csplit :  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

ct  -  spawn  getty  to  a  remote  terminal  (call  terminal) 
SYNOPSIS 

ct  [-w  n]  [-x  n]  [-h]  [-v]  [-s  speed]  telno... 
DESCRIPTION 

ct  dials  telno,  the  telephone  number  of  a  modem  that  is  attached  to  a  terminal,  and  spawns  a  getty(lM) 
process  to  that  termi  nal . 

ct  tries  each  line  listed  in  file  /etc/uucp/Devices  until  it  finds  an  available  line  with  appropriate 
attributes  or  runs  out  of  entries.  If  no  lines  are  free,  ct  asks  whether  it  should  wait  for  a  line,  and  if  so, 
how  many  minutes  it  should  wait  before  giving  up.  ct  searches  again  for  an  available  line  at  one-minute 
intervals  until  the  specified  limit  is  exceeded.  Note  that  normally,  ct  disconnects  the  current  tty  line,  so 
that  the  line  can  answer  the  incoming  call.  This  is  because  ct  assumes  that  the  current  tty  line  is  con- 
nected to  the  termi  nal  to  spawn  the  getty  process. 

The  telno  argument  specifies  the  telephone  number,  which  can  be  composed  of  characters  0  through  9,  -, 
=,  *,  and  #.  Use  equal  signs  to  signify  secondary  dial  tones  and  minus  signs  for  delays  at  appropriate 
places.  The  maximum  length  of  telno  is  31  characters.  If  more  than  one  telephone  number  is  specified,  ct 
tries  each  in  succession  until  one  answers;  thisisuseful  for  specifying  alternate  dialing  paths. 

When  ct  disconnects  the  current  line,  getty  should  not  be  spawned  on  this  line  if  ct  is  going  to  make 
use  of  the  same  line  to  reconnect.  To  do  this,  set  the  entry  for  this  line  in  the  inittab  file  to  uugetty 
instead  of  getty  (see  inittab(4)). 

Options 

ct  recognizes  the  following  options  and  command-line  arguments: 

-wn  I  nstruct  ct  to  wait  for  a  line  a  maximum  of  n  number  of  minutes,  if  lines  are  busy.  If 

this  option  is  specified,  ct  does  not  query  the  user  about  whether  to  wait  for  a  line. 

-xn  Produce  detailed  output  from  program  execution  on  the  standard  error  output.  This 

option  is  used  for  debugging.  The  debugging  level  n  is  a  single  digit;  the  most  useful 
value  is  -x9. 

-h  Prevent  ct  from  disconnecting  ("hanging  up")  the  current  tty  line.  This  option  is 

necessary  if  the  user  is  using  a  different  tty  line  than  the  one  used  by  ct  to  spawn  the 
getty. 

-v  Verbose  mode.  The  -v  option  is  used  with  the  -h  option  and  causes  ct  to  send  a 

running  narrative  to  the  standard  error  output  stream. 

-sspeed  Set  the  data  rate  where  speed  is  expressed  in  baud.  The  default  rate  is  1200. 

After  the  user  on  the  destination  terminal  logs  out,  ct  prompts,  Reconnect?  If  the  response  begins 
with  the  letter  n  the  line  is  dropped.  Otherwise,  getty  is  restarted  and  the  login:  prompt  is  printed. 

Of  course,  the  destination  terminal  must  be  attached  to  a  modem  that  can  automatically  answer  incoming 
calls. 

FILES 

/var/adm/ctlog 
/etc/ uucp/Devices 

SEE  ALSO 

cu(l),  login(l),  uucp(l),  getty(lM),  uugetty(lM). 
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NAME 

ctags  -  create  a  tags  file 

SYNOPSIS 

ctags  [-xvFBatwu]  files  ... 

DESCRIPTION 

ctags  makes  a  tags  file  for  ex(l)  (or  vi  (1))  from  the  specified  C,  Pascal  and  Fortran  sources.  A  tags  file 
gives  the  locations  of  specified  objects  (for  C,  functions,  macros  with  argments,  and  typedefs;  Pascal,  pro- 
cedures, programs  and  functions;  Fortran,  subroutines,  programs  and  functions)  in  a  group  of  files.  Each 
line  of  the  tags  file  contains  the  object  name,  the  file  in  which  it  is  defined,  and  an  address  specification  for 
the  object  definition.  Output  is  sorted  in  ascending  collation  order  (see  Environment  Variables  below).  All 
objects  except  C  typedefs  are  searched  with  a  pattern,  typedefs  with  a  line  number.  Specifiers  are  given  in 
separate  fields  on  the  line,  separated  by  spaces  or  tabs.  Using  the  tags  file,  ex  can  quickly  find  these 
objects'  definitions. 

-x  Cause  ctags  to  print  a  simple  function  index.  This  is  done  by  assembling  a  list  of  function 
names,  file  names  on  which  each  function  is  defined,  the  line  numbers  where  each  function 
name  occurs,  and  the  text  of  each  line.  The  list  is  then  printed  on  the  standard  output.  No 
tags  file  is  created  or  changed. 

-v  Produce  a  page  index  on  the  standard  output.  This  listing  contains  the  function  name,  file 
name,  and  page  number  within  that  file  (assuming  56-linepages  to  match  pr(l)). 

Files  whose  name  ends  in  .cor  .h  are  assumed  to  be  C  source  files  and  are  searched  for  C  routineand 
macro  definitions.  Others  are  first  examined  to  see  if  they  contain  any  Pascal  or  Fortran  routine 
definitions;  if  not,  they  are  processed  again  looking  for  C  definitions. 

Other  options  are: 

-F       Use  forward  searching  patterns  (/.../)  (default). 

-B       Use  backward  searching  patterns  (?...?). 

-a  Add  the  information  from  the  files  to  the  tags  file.  Unlike  re-building  the  tags  file  from  the 
original  files,  this  can  cause  the  same  symbol  to  be  entered  twice  in  the  tags  file.  This  option 
should  be  used  with  caution  and  then  only  in  very  special  circumstances. 

-t       Create  tags  for  typedefs. 

-w       Suppress  warning  diagnostics. 

-u  Update  the  specified  files  in  tags;  that  is,  all  references  to  those  files  are  deleted,  and  the  new 
values  are  added  to  the  file  as  in  -a  above.  (Beware:  this  option  is  implemented  in  a  way 
which  is  rather  slow;  it  is  usually  faster  to  simply  rebuild  the  tags  file.) 

The  tag  main  is  treated  specially  in  C  programs.  The  tag  formed  is  created  by  adding  M  to  the  beginning 
of  name  of  the  file,  with  any  trailing  .  c  removed,  and  leading  pathname  components  also  removed.  This 
makes  use  of  ctags  practical  in  directories  with  more  than  one  program. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  order  in  which  the  output  is  sorted. 

LC_CTYPE  determines  the  interpretation  of  the  single-  and/or  multi-byte  characters  within  comments  and 
string  literals. 

If  LC_COLLATE  or  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  ctags  behaves  as  if  all  internationalization  variables  are  set  to  "C". 
Seeenvi  ron(5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported  with  the  exception  that  multi-byte  character  file 
names  are  not  supported. 
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DIAGNOSTICS 

Too  many  entries  to  sort . 

An  attempt  to  get  additional  heap  space  failed;  the  sort  could  not  be  performed. 

Unexpected  end  of  function  in  file  file,   line  line. 
The  tags  file  may  be  incorrect. 

A  }  character  was  found  unexpectedly  in  the  first  column.  This  can  lead  to  incorrect  entries  in  the 
tags  file. 

Duplicate  entry  in  file  file,    line  line:  name.      Second  entry  ignored. 

The  same  name  was  detected  twice  in  the  same  file.  A  tags  entry  was  made  only  for  the  first  name 
found. 

Duplicate  entry  in  files  fi  I  el  andfile2:  name  (Warning  only). 

The  same  name  was  detected  in  two  different  files.  A  tags  entry  was  made  only  for  the  first  name 
found. 

EXAMPLES 

Create  a  tags  file  named  tags  in  the  current  directory  for  all  C  source  (*  .c)  files  and  all  header  (*  .h) 
files  in  the  current  directory: 

ctags  * . [ch] 

Once  the  tags  file  exists  in  the  current  directory,  it  can  be  used  with  commands  that  support  tag  files  (such 
as  vi  (see  vi  (1)). 

Use  the  tags  file  with  vi  to  edit  a  particular  function  myfunc()  located  in  one  of  the  source  files: 
vi  -t  myfunc 

While  editing  a  C  source  file  using  vi,  use  the  ex-mode  tag  command  to  edit  function  myfunc  ()  : 

: tag  myfunc 
Use  vi  to  find  main()  in  filemyprog.  c: 

vi  -t  Mmyprog 

While  using  vi,  find  main  ()  in  file  myprog.  c  (does  not  have  to  be  the  file  currently  being  edited): 
: tag  Mmyprog 

WARNINGS 

Recognition  of  functions,  subroutines,  and  procedures  for  Fortran  and  Pascal  is  done  in  a 
very  simple  way.  No  attempt  is  made  to  deal  with  block  structure;  if  there  are  two  Pascal  procedures  in 
different  blocks  with  the  same  name,  a  warning  message  is  generated. 

The  method  of  deciding  whether  to  look  for  C  or  Pascal  and  Fortran  functions  is  an  approximation,  and  can 
befooled  by  unusual  programs. 

ctags  does  not  know  about  #if  def  s  and  Pascal  types. 
It  relies  on  the  input  being  well  formed  to  detect  typedefs. 
Use  of  -tx  shows  only  the  last  line  of  typedefs. 

ex  is  naive  about  tags  files  with  several  identical  tags;  it  simply  chooses  the  first  entry  its  (non-linear) 
search  finds  with  that  tag.  Such  files  can  be  created  with  either  the  -u  or  -a  options  or  by  editing  a  tags 
file. 

If  more  than  one  (function)  definition  appears  on  a  single  line,  only  the  first  definition  is  indexed. 
AUTHOR 

ctags  was  developed  by  the  University  of  California,  Berkeley. 
FILES 

tags  output  tags  file 

OTAGS  temporary  file  used  by  -u 
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SEE  ALSO 

ex(l),  vi(l). 

STANDARDS  CONFORMANCE 

ctags: XPG4 
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NAME 

cu  -  call  another  (UNIX)  system;  terminal  emulator 
SYNOPSIS 

cu  [-s  speed]  [-1  line]  [-h]  [-q]  [-t]  [-d  level]  [-e|-o]  [-m]  [-n]  [telno  |  systemnamel  dir  ] 
XPG4  Syntax: 

cu  [-s  speed]  [-1  line]  [-h]  [-q]  [-t]  [-d]  [-e|-o]  [-m]  [-n]  [telno  |  systemnamel  dir  ] 
DESCRIPTION 

cu  calls  up  another  system,  which  is  usually  a  UNIX  operating  system,  but  can  be  a  terminal  or  a  non- 
UNIX  operating  system,  cu  manages  all  interaction  between  systems,  including  possible  transfers  of 
ASCII  files. 

Options 

cu  recognizes  the  following  options  and  command-line  arguments: 

-sspeed  Specify  the  transmission  speed  (110,  150,  300,  600,  1200,  2400,  3600,  4800,  7200,  9600, 

19200).  Thedefault  valueis300. 

-lline  Specify  a  device  name  to  use  as  the  communication  line.  Thiscan  be  used  to  override 

searching  for  the  first  available  line  having  the  right  speed.  When  the  -1  option  is 
used  without  the  -s  option,  the  speed  of  a  line  is  obtained  from  file 
/etc/uucp/Devices.  When  the  -1  and  -s  options  are  used  simultaneously, 
cu  searches  /etc/uucp/Devices  to  determine  whether  the  requested  speed  for 
the  requested  line  is  available.  If  so,  the  connection  is  made  at  the  requested  speed; 
otherwise,  an  error  message  is  printed  and  the  call  is  not  made.  The  specified  device 
is  usually  a  directly  connected  asynchronous  line  (such  as  /dev/ttyapb).  In  this 
case,  a  telephone  number  is  not  required,  but  the  string  dir  can  be  used  to  specify 
that  a  dialer  is  not  required.  If  the  specified  device  is  associated  with  an  auto-dialer,  a 
telephone  number  must  be  provided. 


-h  Emulate  local  echo,  supporting  calls  to  other  computer  systems  that  expect  terminals 

to  beset  to  half-duplex  mode. 

-q  Use  ENQ/ACK  handshake  (remote  system  sends  ENQ,  cusendsACK.) 

-t  Used  when  dialing  an  ASCI  I  terminal  that  has  been  set  to  auto-answer.  Appropriate 

mapping  of  carriage-return  to  carriage-return-line-feed  pairs  is  set. 

-dlevel  Print  diagnostic  traces,  level  is  a  number  from  0-9,  where  higher  level  s  produce  more 

detail  in  the  diagnostic  messages. 

-d  (XPG4  only.)  Print  diagnostic  traces.  The  level  is  always  9. 

-e  (-o)         Generate  even  (odd)  parity  for  data  sent  to  the  remote. 

-m  Specify  a  direct  line  that  has  modem  controls.  Modem  controls  are  ignored  by  cu. 

-n  Cause  the  telephone  number  that  cu  dials  to  be  requested  interactively  from  the  user 

rather  than  taking  it  from  the  command  line. 

telno  When  using  an  automatic  dialer,  telno  is  the  telephone  number,  with  equal  signs  for 

secondary  dial  tone  or  minus  signs  for  delays  appropriately  placed  in  the  telno  string. 


systemname  A  UUCP  system  name  can  be  used  instead  of  a  telephone  number  (see  uucp(l));  in 
this  case,  cu  obtains  an  appropriate  direct  line  or  telephone  number  from 
/etc/uucp/Systems  (including  appropriate  baud  rate),  cu  dials  each  telephone 
number  or  direct  line  for  systemname  in  the  Systems  file  until  a  connection  is  made 
or  all  the  entries  are  tried. 

dir  Using  dir  ensures  that  cu  uses  the  line  specified  by  the  -1  option. 

After  making  the  connection,  cu  runs  as  two  processes: 

•  transmit  process  reads  data  from  the  standard  input  and,  except  for  lines  beginning  with  ~,  passes 
it  to  the  remote  system; 

•  receive  process  accepts  data  from  the  remote  system  and,  except  for  lines  beginning  with  ~,  passes 
it  to  the  standard  output. 
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Normally,  an  automatic  DC3/DC1  protocol  is  used  to  control  input  from  the  remote  to  ensure  that  the  buffer 
is  not  overrun.  "Prompt  handshaking"  can  be  used  to  control  transfer  of  ASCII  files  to  systems  that  have 
no  type-ahead  capability  but  require  data  to  be  sent  only  after  a  prompt  is  given.  This  is  described  in  detail 
below.  Lines  beginning  with  ~  have  special  meanings. 

Transmit  Process  Commands 

The  transmit  process  interprets  the  foil  owing  commands: 

-.,  "..  Terminate  the  conversation.  On  hard-wired  lines,  ~.  sends  several  EOF  characters 
to  log  out  the  session,  whereas  ~.  .  suppresses  the  EOF  sequence.  In  general  the 
remote  hard-wired  machine  is  unaware  of  the  disconnect  if  "..  is  used.  On  dial-up 
connections,  ~.  and  ~.  .  do  not  differ. 


~ ! 

~!cmd  ... 
~& 

~&cmd  ... 
~  |  cmd 


~l 

~$cmd 
~%cd 


Escape  to  an  interactive  shell  on  the  local  system. 
Run  cmd  on  the  local  system  (via  sh  -c). 

Similar  to  ~!  but  kill  the  receive  process,  restarting  it  upon  return  from  the  shell. 
Thisisuseful  for  invoking  sub-processes  that  read  from  the  communication  line  where 
the  receive  process  would  otherwise  compete  for  input. 

Run  cmd  on  the  local  system  (via  sh  -c)  and  kill  the  receive  process,  restarting  it 
later. 

Pipe  incoming  data  from  the  remote  system  through  the  standard  input  to  cmd  on  the 
local  system.  To  terminate,  reset  with  either  a  ~&  or  ~|  command. 

Resets  the  receive  process  following  a  ~  |  cmd  command. 

Run  cmd  locally  and  send  its  output  to  the  remote  system. 

Change  the  directory  on  the  local  system.  Note:  ~  !  cd  causes  the  command  to  be 
run  by  a  sub-shell,  causing  a  return  to  the  current  directory  upon  completion. 

~%take  remotesourcefile  [  localdestinationfile] 

Copy  file  remote  source  file  from  the  remote  system  to  file  local  destination  file  on 
the  local  system.  If  local  destination  file  is  not  specified,  the  remote  source  file  argu- 
ment is  used  in  both  places. 

~%put  I ocal  source  fi  I e  [  remotedesti  nati on  fi  I e  ] 

Copy  file  localsourcefileon  local  system  to  file  remotedesti  nati  onfil  eon  remote  sys- 
tem. If  remotedestinationfile  is  not  specified,  the  I  ocalsourcefile  argument  is  used 
in  both  places. 

~~  ...  Send  the  line  ~  ...  to  the  remote  system.  If  you  use  cu  on  the  remote  system  to 

access  a  thi  rd  remote  system,  send  ~  ~  .  to  cause  the  second  remote  cu  to  exit. 

~%break        Transmit  a  BREAK  to  the  remote  system. 

~%nostop  Toggle  between  DC3/DC1  input  control  protocol  and  no  input  control.  This  is  useful  if 
the  remote  system  does  not  respond  properly  to  the  DC3  and  DC1  characters. 

~%<file  Send  the  contents  of  the  local  file  to  the  remote  system  using  prompt  handshaking. 

The  specified  file  is  read  one  line  at  a  time,  and  each  line  is  sent  to  the  remote  system 
when  the  prompt  sequence  is  received.  If  no  prompt  is  received  by  the  time  the 
prompt  timeout  occurs,  the  line  is  sent  anyway.  If  the  timeout  is  set  to  0  seconds,  or  if 
the  first  character  in  the  prompt  sequence  is  a  null  character  C@),  the  handshake 
always  appears  to  be  satisfied  immediately,  regardless  of  whether  or  not  the  remote 
system  generates  a  prompt.  This  capability  is  intended  mainly  to  facilitate  transfer  of 
ASCII  files  from  HP-UX  to  an  HP  3000  system  running  MPE.  This  is  usually  accom- 
plished by  running  the  MPE  FCOPY  utility  and  giving  the  command 
from=;to=destfile;new  and  then  runningthe  cu  input  diversion  to  send  the  file  to 
FCOPY  which  saves  it  in  destfile.  This  facility  might  be  useful  with  other  systems 
also,  such  as  an  HP  1000  running  RTE. 

~%setpt  n  Specify  the  number  of  seconds  to  wait  for  a  prompt  before  giving  up.  The  default  is  2 
seconds.  Specifying  a  timeout  of  0  seconds  disables  handshaking;  that  is,  handshake 
appears  to  complete  immediately. 

~%setps  xy  Set  the  handshake  prompt  to  the  characters  xy.  The  default  is  DC1.  Thepromptcan 
be  any  one  or  two  characters.  To  specify  a  control  character  for  x  or  y,  use  the  Ctrl-X 
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form  where  a  circumflex  (ASCII  94)  precedes  the  character,  as  in  "X.  A  null  charac- 
ter can  be  specified  with  "@  (A  null  first  character  in  the  prompt  implies  a  "null" 
prompt,  which  always  appears  to  be  satisfied.)  A  circumflex  is  specified  by  " 

~%>[>]file  Divert  output  from  the  remote  system  to  the  specified  file  until  another  ~%>  com- 
mand is  given.  When  an  output  diversion  is  active,  typing  ~%>  terminates  it, 
whereas  ~%>  anotherfile  terminates  it  and  begins  a  new  one.  The  output  diversion 
remains  active  through  a  ~&  subshell,  but  unpredictable  results  can  occur  if 
input/output  diversions  are  intermixed  with  ~%take  or  ~%put.  The  ~%»  com- 
mand appends  to  the  named  file.  Note  that  these  commands,  which  are  interpreted 
by  the  transmit  process,  are  unrelated  to  the  ~>  commands  described  below,  which 
are  i  nterpreted  by  the  receive  process. 

~susp  Suspend  the  cu  session,  susp  is  the  suspend  character  set  in  the  terminal  when  cu 

was  invoked  (usually  "Z  —  see  stty(l)).  As  in  all  other  lines  starting  with  tilde,  a 
~susp  line  must  be  terminated  by  pressing  Return. 

Receive  Process 

The  receive  process  normally  copies  data  from  the  remote  system  to  its  standard  output.  A  line  from  the 
remote  that  begins  with  ~>  initiatesan  output  diversion  toa  file.  The  complete  sequence  is: 

->[>]:  file 

zero  or  more  lines  to  be  written  to  file 
~> 

Data  from  the  remote  is  diverted  (or  appended,  if  »  is  used)  to  file.  The  trailing  ~>  terminates  the 
diversion. 

The  use  of  ~%put  requires  stty(l)  and  cat(l)  on  the  remote  side.  It  also  requires  that  the  current  erase 
and  kill  characters  on  the  remote  system  be  identical  to  the  current  ones  on  the  local  system.  Backslashes 
are  inserted  at  appropriate  places. 

The  use  of  ~%take  requires  that  the  remote  system  support  the  echo  and  cat  commands  (see  echo(l) 
and  cat(l).  Also,  stty  tabs  mode  should  be  set  on  the  remote  system  if  tabs  are  being  copied  without 
expansion.  When  connecting  to  a  machine  that  uses  the  eighth  bit  as  a  parity  bit,  stty  istrip  mode 
should  beset  on  the  local  system. 

When  cu  is  used  on  system  X  to  connect  to  system  Y  and  subsequently  used  on  system  Y  to  connect  to  sys- 
tem Z,  commands  on  system  Y  can  be  executed  if  is  used.  For  example,  using  the  keyboard  on  system 
X,  uname  can  be  executed  on  Z,  X,  and  Y  as  follows  where  lines  1,  3,  and  5  are  keyboard  commands,  and 
lines  2,  4,  and  6  are  system  responses: 

uname 
Z 

~ !  uname 
X 

~~ ! uname 
Y 

I  n  general,  ~  causes  the  command  to  be  executed  on  the  original  machine;  ~~  causes  the  command  to  be 
executed  on  the  next  machine  in  the  chain. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 
If  any  internationalization  variable  contains  an  invalid  setting,  cu  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Exit  code  iszerofor  normal  exit;  non-zero  (various  values)  otherwise. 
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EXAMPLES 

To  dial  a  system  whose  number  is  9  201  555  1212  using  1200  baud: 

cu  -sl200  9=2015551212 
If  the  speed  isnot  specified,  300  is  the  default  value. 
To  log  in  on  a  system  connected  by  a  direct  line: 

cu  -1/dev/ttyXpX  dir 
To  dial  a  system  with  the  specific  line  and  a  specific  speed: 

cu  -sl200  -1/dev/ttyXpX  dir 
To  dial  a  system  using  a  specific  line: 

cu  -1/dev/culXpX  2015551212 
To  use  a  system  name  (yyyzzz ): 

cu  yyyzzz 
To  connect  directly  to  a  modem: 

cu  -1/dev/culXX  -m  dir  cu  -1/dev/culXX  -m  dir 

WARNINGS 

cu  buffers  input  internally. 

AUTHOR 

cu  was  developed  by  AT&T  and  HP. 

FILES 

/etc/ uucp/ Systems 
/etc/ uucp/Devices 
/etc/ uucp/Dialers 

/var/spool/locks/LCK.  .  (tty-device) 
/dev/null 

SEE  ALSO 

cat(l),  ct(l),  echod),  stty(l),  uname(l),  uucp(l),  uuname(l). 

STANDARDS  CONFORMANCE 

cu:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

cue-  HP  Character -Terminal  User  Environment  (CUE) 

SYNOPSIS 

/usr/bin/cue 

DESCRIPTION 

cue  provides  an  easy-to-use,  attractive,  customizable  environment  that  allows  users  on  Series  800  hp-ux 
systems  to  easily  identify  themselves  to  the  system  and  begin  a  work  session.  See  dependencies  for  sup- 
ported termi  nal  types. 

A  menubar  is  avail ablefor  changing  the  native  language  of  the  session,  changing  the  type  of  session  to  start 
upon  a  successful  login,  or  getting  on-line  help.  To  obtain  context-sensitive  help  at  any  time,  press  the  func- 
tion key  labeledHELP  (f  1). 

A  pulldown  menu  and  function  keys  (f  1-f  8)  are  displayed,  allowing  the  user  to  modify  various  options  or  to 
get  help.  Before  the  login  is  initiated,  the  user  has  the  option  of  interactively  changing  the  native  language 
of  the  session  and  the  type  of  session  to  start  upon  a  successful  login. 

The  default  native  language  is  C,  but  the  language  is  easily  modifiable  by  entering  the  Language  Menu 
which  is  accessible  by  selecting  the  Configuration  item  in  the  menu  bar.  The  native  language  can  also  be 
specified  as  a  parameter  to  cuegetty  (see  cuegetty(lM)). 

The  default  session  type  is  the  POSIX  shell,  sh,  but  the  session  type  can  be  easily  changed  to  tsm,  keysh, 
or  csh  by  entering  the  Session  Type  Menu  which  is  accessible  by  selecting  the  Configuration  item  in  the 
menu  bar. 

Thefollowing  standard  login  features  are  available: 

•  password  agi  ng 

•  logging  invalid  login  attempts  in  /var/adm/btmp 

•  list  of  valid  ttys  for  super-user  login 

CUE  displays  a  visual  screen  that  prompts  for  the  username  and  corresponding  password.  If  your  user- 
name  does  not  havea  password,  press  the  <carriage  return>  key  to  ski  p  this  field.  Terminal  echoisturned 
off  (where  possible)  during  typing  of  the  password  so  that  it  will  not  appear  on  any  written  record  of  the 
session.  After  three  unsuccessful  login  attempts,  a  hangup  signal  is  issued. 

If  password  aging  has  been  invoked  by  the  super-user  on  your  behalf,  your  password  may  have  expired.  I  n 
this  case,  you  will  be  diverted  intopasswd  to  change  it,  after  which  you  can  attempt  to  login  again.  See 
passwd(l). 

If  login  is  not  successfully  completed  within  a  certain  period  of  time  (e.g.,  five  minutes),  the  terminal  may 
be  silently  disconnected. 

After  a  successful  login,  the  accounting  files  are  updated,  initializing  the  user  and  group  ids,  group  access 
list,  and  working  directory.  If  the  session  type  chosen  is  tsm,  the  SHELL  to  start  in  each  tsm  session  is 
determined  from  corresponding  user  entries  in  the  /etc/passwd  file,  cue  then  forks  the  appropriate 
shell  by  using  the  last  component  of  the  shell  pathname  preceded  by  a  -  (for  example,  -sh  or  -ksh). 
When  the  session  type  is  invoked  with  its  name  preceded  by  a  minus  in  this  manner,  the  shell  performs  its 
own  initialization,  including  execution  of  profile,  login,  or  other  initialization  scripts. 

For  example,  if  the  user  login  shell  is  sh(l)  or  ksh(l)  the  shell  executes  the  profile  files  /etc/profile 
and  $HOME/ .prof  ile  if  they  exist  (and  possibly  others  as  well).  Depending  on  the  contents  of  the 
profile  files,  messages  regarding  mail  in  your  mail  file  or  any  messages  you  may  have  received  since  your 
last  login  may  be  displayed.  At  this  point,  cuesession  is  started  to  perform  accounting  procedures,  display 
messages,  and  start  your  session. 

If  /var/adm/btmp  is  present,  all  unsuccessful  login  attempts  are  logged  to  this  file.  This  feature  is  dis- 
abled if  the  file  is  not  present.  A  summary  of  bad  login  attempts  can  be  viewed  by  users  with  appropriate 
privileges  by  using  lastb,  see  last(lM). 

If  /etc/securetty  is  present,  login  security  is  in  effect,  meaning  that  only  users  with  appropriate 
privileges  are  allowed  to  login  successfully  on  the  ttys  listed  in  this  file.  Restricted  ttys  are  listed  by  device 
name,  one  per  line.  Valid  tty  names  are  dependent  on  installation.  Some  examples  could  be  console, 
ttyOl,  ttyal,  etc.  Note  that  this  feature  does  not  inhibit  a  normal  user  from  using  su. 
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Starting  Cue 

There  are  several  methods  that  can  be  used  to  start  cue. 

•  An  entry  for  cuegetty  can  be  placed  in  the  /etc/inittab  file.  See  cuegetty(lM)).  This  is 
the  preferred  method  as  the  user  does  not  need  to  do  anything  further  to  start  cue. 

•  Start  cue  from  the  command  line  by  typing:  cue. 

•  Start  cue  by  making  it  the  last  entry  in  the  user's  .  login  configuration  file. 

Multiple  cue  logins  may  run  simultaneously  on  separate  terminals  attached  to  the  same  local  host, 
cuegetty  can  be  configured  in  the  /etc/inittab  file  for  all  users. 

Remote  users  to  the  CUE  system  must  access  CUE  by  entering  the  cue  command  at  the  command-line 
prompt  or  as  the  last  item  in  the  user's  .  login  configuration  file. 

EXTERNAL  INFLUENCES 
Environment  Variables 

cue  invokes  the  user's  session  with  the  foil  owing  default  environment: 

CUESESSION  is  set  to  the  session  type  selected.  Valid  values  are: 

/usr/bin/sh  POSIX  Shell  (DEFAULT) 

/usr/bin/tsm  manages  up  to  10  sessions  at  once 

/usr/bin/keysh        Easy  Context-Sensitive  Softkey  Shell 
/usr/bin/ksh  Korn  Shell 

/usr/bin/csh  C  Shell 

HOME  i  s  set  to  the  home  di  rectory  of  the  user 

LANG  is  set  to  the  native  language  selected  (C  is  the  default) 

LOGNAME        is  set  to  the  user  name 

MAIL  is  set  to  /var/mail/ $LOGNAME 

NLSPATH       is   set    to   the    path    applications   search    for    NLS    message   catalogs,  usually 
/usr/lib/nls/%L/%N . cat 

PATH  is  set  to  the  path  to  be  searched  for  commands  :  /usr/bin 

SHELL  is  set  to  the  user's  default  shell  (from /etc/passwd) 

Several  methods  are  availableto  modify  or  add  to  this  list  depending  on  the  desired  scope  of  the  resulting 
environment  variable. 

Basic  environment  variables  can  be  set  for  all  CUE  users  on  a  system  by  setting  the  values  in 
/etc/profile  and  /etc/csh.  login.  Personal  environment  variables  can  beset  on  a  per-user  basis 
in  the  script  file  $HOME/  .profile  for  sh  and  ksh  users  or  .  cshrc  for  csh  users. 

Note  that  alias  and  function  definitions  need  to  be  included  in  the  file  specified  by  ENV  for  ksh,  as  this  file 
will  be  sou  reed  for  each  invocation  of  the  shell.  For  csh  users,  the  .cshrc  file  should  be  structured  such 
that  it  cannot  generate  any  output  on  standard  output  or  standard  error,  including  occasions  when  it  is 
invoked  without  an  affiliated  terminal.  The  rep  command  sources  the  .cshrc  file  and  any  output  gen- 
erated by  this  file,  even  to  standard  error,  causes  problems.  Commands  such  as  stty  should  be  placed  in 
the  .  login  file,  not  in  .  cshrc,  so  that  their  output  cannot  affect  rep. 

For  users  with  appropriate  privileges,  PATH  is  augmented  to  include /etc. 


Section  1-158 


-2- 


HP-UX  Release  Hi:  December  2000 


cue(l) 


(Series  800  Only) 


cue(l) 


VT320 Terminal  Support 

Because  the  VT320  terminal  has  predefined  local  functions  for  keys  labeled  as  Fl,  F2,  F3  and  F4,  users 
should  use  following  mapping  when  they  desire  to  use  function  keys: 


H  P  or  Wyse60  VT320  or  H  P  700/60  i  n  VT320  mode 

Fl  PF2  ! 

F2  PF1  ! 

F  3  space  bar 

F4  PF3  ! 

F5  F10,  [  EXIT  ],  F5  * 

F6  none 

F7  F18,  first  unlabeled  key  to  right  of  Pause/Break* 

F8  F19,  second  unlabeled  key  to  right  of  Pause/Break* 


*      When  using  PC-AT  keyboard  with  HP  700/60  in  VT320  mode 

!      See  "Configuration:  HP  700/60in  DEC  mode,  or  DEC  terminals  with  PC-AT  type  keyboard" 

Further,  since  DEC  terminals  do  not  support  softkey  menu,  no  such  menu  is  displayed  on  these  termi- 
nals. 

Many  applications  tend  to  use  TAB  for  forward  navigation  (moving  from  one  field  to  another)  and 
shift-TAB  is  used  for  backward  navigation.  Users  having  DEC  terminals  or  using  terminals  in  DEC 
emulation  modes  such  as  VT100  or  VT320  may  note  that  these  terminals/emulators  may  give  out 
same  character  for  TAB  and  shift-TAB.  As  such,  it  is  i mpossi bl e  for  an  application  to  distinguish 
between  TAB  and  shift-TAB,  and  both  of  them  treated  as  if  a  TAB  key  was  pressed.  It  might  present 
slight  overhead  to  users  in  case  they  want  to  go  backwards.  Now  instead,  they  should  complete  rest  of 
the  inputs  and  get  back  to  the  desired  field  later. 

VT 100 Terminal  Support 

VT100  does  not  allow  the  (fl-f8)  function  keys  to  be  configured.  Therefore,  the  following  keyboard  map- 
pings will  apply  to  VT100  terminals: 


H  P  or  Wyse60 

VT100  or  H  P  700/60  in  VT100  mode 

Fl 

PF2  ! 

F2 

PF1  ! 

F3 

space  bar 

F4 

[PF  3],  [space  bar]  or  [PF  3],  [=]  ! 

F5 

return 

F6 

none 

F7 

none 

F8 

none 

!      See  "Configuration:  HP  700/60in  DEC  mode,  or  DEC  terminals  with  PC-AT  type  keyboard" 

Further,  since  DEC  terminals  do  not  support  softkey  menu,  no  such  menu  is  displayed  on  these  termi- 
nals. 

Many  applications  tend  to  use  TAB  for  forward  navigation  (moving  from  one  field  to  another)  and 
shift-TAB  is  used  for  backward  navigation.  Users  having  DEC  terminals  or  using  terminals  in  DEC 
emulation  modes  such  as  VT100  or  VT320  may  note  that  these  terminals/emulators  may  give  out 
same  character  for  TAB  and  shift-TAB.  As  such,  it  is  i  mpossi  bl  e  for  an  application  to  distinguish 
between  TAB  and  shift-TAB,  and  both  of  them  treated  as  if  a  TAB  key  was  pressed.  It  might  present 
slight  overhead  to  users  in  case  they  want  to  go  backwards.  Now  instead,  they  should  complete  rest  of 
the  inputs  and  get  back  to  the  desired  field  later. 

Configuration:  HP  700/60 terminal  in  DEC  mode,  or  DEC  terminal  with  PC-AT  type  keyboard 

Customers  using  the  foil  owing  configuration  may  want  to  be  aware  of  the  foil  owing  keyboard  difference. 
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It  may  be  possiblefor  a  user  with  the  "HP  700/60  termi nal  in  DEC  mode,  or  DEC  terminal  with  PC-AT  type 
keyboard"  configuration  to  be  told  to  press  function  key  Fl  through  F4  to  achieve  some  desired  result.  For 
HP  700/60  terminal  in  DEC  mode  or  DEC  terminals,  these  functions  keys  may  be  mapped  onto  PF1-PF4 
keys,  (see  "Keyboard  Mappings").  However,  the  PC-AT  type  keyboard  does  not  provide  PF1,  PF2,  PF3,  or 
PF4keys,  as  does  the  DEC/ANSI  keyboard. 

Keyboard  Mappings 

"N urn  Lock"  mapsto"PFl" 
"/"  maps  to  "PF2" 

"*"  maps  to  "PF3" 

maps  to  "PF4" 

The  "Num  Lock",  "/",  "*",  and  "-"  keys  are  located  on  the  keyboard,  in  a  row,  above  the  number  pad  on 
the  right  side  of  the  keyboard.  Please  note  that  although  this  keyboard  is  called  a  PC-AT  type  key- 
board, it  is  supplied  by  HP.  A  PC-AT  type  keyboard  can  be  recognized  by  location  of  ESC  key  at  the 
left-top  of  the  keyboard. 

Wyse60 Terminal  Support 

On  Wyse60,  use  DEL  (located  next  to  Backspace)  key  to  backspace.  On  an  HP  700/60  with  a  PC-AT  type 
keyboard  in  Wyse60  mode,  the  DEL  key  is  located  in  the  bottom  row  on  the  number  pad. 

Wyse60  terminals  provide  a  single  line  to  display  softkey  labels  unlike  HP  terminals  which  provide  two 
lines.  Sometimes  this  may  result  in  truncated  softkey  labels.  For  example,  "Help  on  Context"  label  for  Fl 
may  appear  as  "Help  on  C".  Some  standard  labels  for  screen-oriented  applications  such  as  SAM  and  swin- 
stall  are  as  follows: 

On  wyse60  may  appear  as  ..  means 

HelpOnC  HelpOn  Context 

Select/D  Select/Deselect 

Menubar  Menubar  on/off 

I  nternationalization 

All  screens,  labels,  and  messages  are  localizable.  The  message  catalog  cue. cat  contains  the  localized 
representations  of  the  default  labels  and  messages,  cue  will  read  the  appropriate  message  catalog  indi- 
cated by  the  LANG  environment  variable  and  display  the  localized  strings.  By  selecting  a  native  language 
in  the  Language  Menu,  the  language  of  the  cue  screens  and  the  future  work  session  can  be  specified.  If 
the  the  message  catalog  exists  for  cue  in  the  language  selected,  cue  will  be  redisplayed  in  that  language. 
If  not,  the  cue  screens  will  continue  in  the  current  language  and  the  work  session  that  is  started  after  a 
successful  login  will  be  started  in  the  language  selected.  In  either  case,  the  LANG  environment  variable 
will  beset  appropriately  for  the  resulting  work  session. 

If  cue  will  be  started  on  the  command  line  or  as  the  last  item  in  the  .  login  file,  the  cue  screens  will  be 
brought  up  using  the  language  specified  by  the  LANG  environment  variable.  If  cue  screens  do  not  exist, 
then  the  default  native  language,  C,  will  be  used. 

To  use  cue  with  Asian  languages,  the  AWTERM  environment  variable  must  be  set  to  hpterm-asian . 
This  will  allow  the  text  in  Asian  fonts  to  be  displayed  properly  by  cue. 

If  cue  will  be  started  by  cuegetty,  it  is  possible  to  start  up  the  cue  Login  Screens  in  a  language  other 
than  the  default,  C,  by  invoking  cuegetty  with  the  -L  nls  language  option.  Of  course,  cue  screens  and 
the  cue .  cat  file  must  exist  for  the  nlslanguage  specified. 

DEPENDENCIES 

cue  is  availableonly  on  Series  800  systems,  and  is  compatible  only  with  the  foil  owing  terminals: 
HP  700/92       HP  700/94       HP  2392       HP  2394       VT320       VT100       WYSE  60 

WARNINGS 

cue  is  an  HP  proprietary  command,  which  will  beobsoleted  in  a  future  release,  and  is  not  portable  to  other 
vendor's  platforms. 
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FILES 

/ var/ adm/btmp 

/etc/ logingroup 

/etc/motd 

/etc/passwd 

/etc/profile 

/ etc/ securetty 

/etc/utmp 

/ var/ adm/ wtmp 

/var  /mail/  your-name 

/usr /bin/cue 

/ usr/ sbin/ cuegetty 

/ usr/ newconf ig/ etc/ cue 

/etc /cue. dm 

/usr/lbin/cuesession 

/usr/lib/nls/$LANG/cue 

/usr/ share/man/manl . Z/ 

/usr/ share/man/manlm. Z 


history  of  bad  login  attempts 
group  file  -  defines  group  access  lists 
message- of-the-day 

password  file  -  defines  users,  passwords,  and  primary  groups 

system  profile  (initialization  for  all  users) 

I  i  st  of  val  i  d  ttys  for  root  I  ogi  n 

users  currently  logged  in 

history  of  logins,  logouts,  and  date  changes 

mailbox  for  user  your-name 

cue  executable 

cuegetty  executable 
inittab  tempi  ate  for /etc/ inittab 

screen  descriptions 

starts  selected  session  type 
cat      NLS  message  catalog 
cue .  1    man  page  for  cue(l) 
/cuegetty .  lm    man  page  for  cuegetty(lM) 


SEE  ALSO 

csh(l),  cuegetty(lM),  env(l),  keysh(l),  ksh(l),  login(l),  passwd(l),  sh(l),  tsm(l),  btmp(4),  environ(5), 
hpnls(5),  lang(5). 
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NAME 

cut  -  cut  out  (extract)  selected  fields  of  each  line  of  a  file 

SYNOPSIS 

cut  -c  list  [file  ... ] 

cut  -b  list  [-n]  [file  ...] 

cut  -f  list  [-d  char]  [-s]  [file  ...] 

DESCRIPTION 

cut  cuts  out  (extracts)  columns  from  a  table  or  fields  from  each  line  in  a  file;  in  data  base  parlance,  it 
implements  the  projection  of  a  relation.  Fields  as  specified  by  list  can  be  fixed  length  (defined  in  terms  of 
character  or  byte  position  in  a  line  when  using  the  -c  or  -b  option),  or  the  length  can  vary  from  line  to 
line  and  be  marked  with  a  field  delimiter  character  such  as  the  tab  character  (when  using  the  -f  option), 
cut  can  be  used  as  a  filter;  if  no  files  are  given,  the  standard  input  is  used. 

When  processing  single-byte  character  sets,  the  -c  and  -b  options  are  equivalent  and  produce  identical 
results.  When  processing  multi-byte  character  sets,  when  the  -b  and  -n  options  are  used  together,  their 
combined  behavior  isvery  similar,  but  not  identical  to  the  -c  option. 

Options 

Options  are  interpreted  as  follows: 

list  A  comma-separated  list  of  integer  byte  (-b  option),  character  (-c  option),  or  field  (-f 

option)  numbers,  in  increasing  order,  with  optional  -  to  indicate  ranges.  For  exam- 
ple: 

1,4,7     Positions  1,  4,  and  7. 
1-3,8     Positions  1  through  3  and  8. 
-5,10     Positions  1  through  5  and  10. 
3-  Position  3  through  last  position. 

-b  list  Cut  based  on  a  list  of  bytes.  Each  selected  byte  is  output  unless  the  -n  option  is  also 

specified. 

-c  list  Cut  based  on  character  positions  specified  by  list  (-c  1-72  extracts  the  first  72  char- 

acters of  each  line). 

-f  list  Where  list  is  a  list  of  fields  assumed  to  be  separated  in  the  file  by  a  delimiter  charac- 

ter (see -d);  for  example,  -f  1,  7  copies  the  first  and  seventh  field  only.  Lineswith 
no  field  delimiters  will  be  passed  through  intact  (useful  for  table  subheadings),  unless 
-s  is  specified. 

-d  char         The  character  following  -d  is  the  field  delimiter  (-f  option  only).  Default  is  tab. 

Space  or  other  characters  with  special  meaning  to  the  shell  must  be  quoted.  Adjacent 
field  delimiters  delimit  null  fields,  char  may  bean  international  code  set  character. 


-n  Do  not  split  characters.  If  the  high  end  of  a  range  within  a  list  is  not  the  last  byte  of  a 

character,  that  character  is  not  included  in  the  output.  However,  if  the  low  end  of  a 
range  within  a  list  is  not  the  first  byte  of  a  character,  the  entire  character  is  included 
in  the  output." 

-s  Suppresses  lines  with  no  delimiter  characters  when  using  -f  option.  Unless  -sis 

specified,  lineswith  no  delimiters  appear  in  the  output  without  alteration. 

Hints 

Use  grep  to  extract  text  from  a  file  based  on  text  pattern  recognition  (using  regular  expressions).  Use 
paste  to  merge  files  line-by-line  in  columnar  format.  To  rearrange  columns  in  a  table  in  a  different 
sequence,  use  cut  and  paste.  See  grep(l)  and  paste(l)  for  more  information. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used 
as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
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default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  cut  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

cut  supports  both  single-  and  multi-byte  character  code  sets.  International  code  set  characters  may  be 
specified  in  the  char  given  to  the  -d  option,  cut  recognizes  the  international  code  set  characters  accord- 
ing to  the  locale  specified  in  the  LC_CTYPE  environment  variable. 

EXAMPLES 

Password  file  mapping  of  user  id  to  user  names: 

cut  -d  :  -f  1,5  /etc/passwd 

Set  environment  variable  name  to  current  login  name: 

name=  rwho  am  i   |   cut  -f  1  -d  "   " * 

Convert  file  source  containing  lines  of  arbitrary  length  into  two  files  where  filel  contains  the  first 
500  bytes  (unless  the  500th  byte  is  within  a  multi-byte  character),  and  f  ile2  contains  the  remainder  of 
each  line: 

cut  -b  1-500  -n  source  >  filel 
cut  -b  500-  -n  source  >  file2 

DIAGNOSTICS 

line  too  long 

Line  length  must  not  exceed  LINE_MAX  characters  or  fields,  including  the  new-line  char- 
acter (see  limits(5). 

bad  list  for  b/c/f  option 

Missing  -b,  -c,  or  -f  option  or  incorrectly  specified  list.  No  error  occurs  if  a  line  has 
fewer  fields  than  the  list  calls  for. 

no  fields  listisempty. 
WARNINGS 

cut  does  not  expand  tabs.  Pipe  text  through  expand(l)  if  tab  expansion  is  required. 

Backspace  characters  are  treated  the  same  as  any  other  character.  To  eliminate  backspace  characters 
before  processing  by  cut,  use  the  fold  or  col  command  (see  fold  (1)  and  col  (1)). 

AUTHOR 

cut  was  developed  by  OSF  and  HP. 

SEE  ALSO 

grep(l),  paste(l). 

STANDARDS  CONFORMANCE 

cut:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

date  -  display  or  set  the  date  and  time 

SYNOPSIS 

date  [-u] 

date  [-u]  +format 

date  [-u]  [mmddhhmm[[cc]yy]] 

date  [-a  [-]sss[ .  fff ]] 

DESCRIPTION 

The  date  command  displays  or  sets  the  current  HP-UX  system  clock  date  and  time.  Since  the  HP-UX  sys- 
tem operates  in  Coordinated  Universal  Time  (UTC),  date  automatically  converts  to  and  from  local  stan- 
dard or  daylight/summer  time,  based  on  your  TZ  environment  variable.  See  Environment  Variables  in 
EXTERNAL  INFLUENCES  below. 

Options 

date  recognizes  the  following  option: 

-u    Input  and  output  values  in  Coordinated  Universal  Time  (UTC),  functionally  equivalent  to 
Greenwich  Mean  Time  (GMT),  instead  of  in  local  time. 

-a  [-]sss[.fff] 

Slowly  adjust  the  time  by  sss .  fff  seconds  (fff  represents  fractions  of  a  second).  This  adjustment 
can  be  positive  or  negative.  The  system's  clock  will  be  sped  up  or  slowed  down  until  it  has 
drifted  by  the  number  of  seconds  specified. 

Formats 

The  date  command  has  two  forms  for  displaying  the  date  and  time  and  one  form  for  setting  them, 
date  [-u] 

Display  the  current  dateandtime.  The  output  is  the  same  as  for  the  %c  formatting  directive 
for  all  languages  except  the  C  default  language.  See  Formatting  Directives  and  EXAMPLES 
below. 

date  [-u]  -Hformat 

Display  the  current  date  and  time  according  to  formatting  directives  specified  in  format, 
which  is  a  string  of  zero  or  more  formatting  directives  and  ordinary  characters.  If  it  contains 
blanks,  enclose  it  in  apostrophes  or  quotation  marks. 

See  Formatting  Directives  below. 

All  ordinary  characters  are  copied  unchanged  into  the  output  string. 

Theoutput  string  isalways terminated  with  a  newline character. 

If  +  is  specified  and  format  is  omitted,  only  a  newline  is  output. 

date  [-u]  [mmddhhmm[[cc]yy]] 

Set  the  HP-UX  system  clock  to  the  date  and  time  specified.  You  require  the  superuser 
privilege. 

If  you  include  the  -u  option,  the  specified  date  and  time  is  assumed  to  be  in  Coordinated 
Universal  Time  (UTC). 

The  numeric  argument  i s  i nterpreted  left  to  right  in  two-digit  pairs  as  follows: 

mm  Month  number  [01-12]. 

dd    Day  number  in  the  month  [01-31]. 

hh    Hour  number  (24-hour  system)  [00-23]. 

mm  Minutenumber  [00-59]. 

cc    Century  minus  one  [19-20]. 

yy    Last  two  digits  of  the  year  number  [70-99,  00-37  (1970-1999,  2000-2037)].  If 
omitted,  the  current  year  is  used. 

If  you  attempt  to  set  the  date  backwards,  date  generates  the  warning, 
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do  you  really  want  to  run  time  backwards? [yes/no] 

Type  yes  or  the  equivalent  for  your  locale  to  set  the  clock  backwards;  anything  else  to  cancel 
the  command. 

When  date  is  used  to  set  the  date,  a  pair  of  date  change  records  is  written  to  the  file 
/var/ adm/wtmp . 

(XPG4  only.)  No  warning  is  generated  if  date  is  set  backwards. 
Formatting  Directives 

The  following  formatting  directives,  shown  without  the  optional  field  width  and  precision  specification,  are 
replaced  by  the  indicated  characters.  If  a  directive  is  not  one  of  the  foil  owing,  the  result  is  undefined. 

The  output  for  digits,  characters,  and  words  depends  on  the  language/locale  settings.  See  Environment 
Variables  in  EXTERNAL  INFLUENCES  below. 

The  examples  assume  that  the  date  command  was  executed  on  Wednesday,  J  anuary  12,  1994  at  7:45:58 
p.m.  Pacific  Standard  Time,  using  the  C  default  language. 

%a  Abbreviated  weekday  name.  For  example,  Wed. 

%A  Full  weekday  name.  For  example,  Wednesday . 

%b  Abbreviated  month  name.  For  example,  Jan. 

%B  Full  month  name.  For  example,  January. 

%c  Current  date  and  time  representation.  For  example,  Wed  Jan  12  19:45:58  1994. 

%C  Century  (the  year  divided  by  100  and  truncated  to  an  integer)  as  a  two-digit  decimal  number 
[00-99].  For  example,  19. 

%d   Day  of  the  month  as  a  two-digit  decimal  number  [01-31].  For  example,  12. 

%e  Day  of  the  month  as  a  two-character  decimal  number  with  leading  space  fill  ["  1"-  "31"  ]. 
For  example,  12. 

%E  Combined  Emperor/Era  nameandyear. 

%H  Hour  (24-hour  clock)  as  a  two-digit  decimal  number  [00-23].  For  example,  19. 

%I  Hour  (12-hour  clock)  as  a  two-digit  decimal  number  [01-12].  For  example,  07. 

%j  Day  of  the  year  as  a  three-digit  decimal  number  [001-366].  For  example,  012. 

%m  Month  as  a  decimal  two-digit  number  [01-12].  For  example,  01. 

%M  Minuteas a  decimal  two-digit  number  [00-59].  For  example,  45. 

%n  Newline  character. 

%N  Emperor/Era  name. 

%o  E  mperor/E  ra  year. 

%p  Equivalent  of  either  AIM  or  PM .  For  example,  PM. 

%R  Timeas%H:%M 

%S  Second  as  a  two-digit  decimal  number  (allows  for  possible  leap  seconds)  [00-61].  For  example, 
58. 

%t  Tab  character. 

%u  Weekday  as  a  one-digit  decimal  number  [1-7  (Monday-Sunday)].  For  example,  3. 

%U  Week  number  of  the  year  (Sunday  as  the  first  day  of  the  week)  as  a  two-digit  decimal  number 
[00-53].  All  days  that  precede  the  first  Sunday  in  the  year  are  considered  to  be  in  week  00. 
For  example,  02. 

%V  Week  number  of  the  year  (Monday  as  the  first  day  of  the  week)  as  a  two-digit  decimal  number 
[01-53].  If  the  week  containing  J  anuary  1  has  four  or  more  days  in  the  new  year  (J  anuary  1  is 
Thursday  or  sooner),  it  is  designated  as  week  01;  otherwise,  (J  anuary  1  is  Friday  or  later),  it  is 
designated  as  the  last  week  of  the  previous  year,  and  the  next  week  is  week  01.  For  example, 
02. 
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%w   Weekday  as  a  one-digit  decimal  number  [0-6  (Sunday-Saturday)].  For  example,  3. 

%W  Week  number  of  the  year  (Monday  as  the  first  day  of  the  week)  as  a  two-digit  decimal  number 
[00-53].  All  days  that  precede  the  first  Monday  in  the  year  are  considered  to  be  in  week  00. 
For  example,  02. 

%x  Current  date  representation.  For  example,  01/12/94 . 

%X  Current  time  representation.  For  example,  19 : 45 : 58 . 

%y  Year  without  century  as  a  two-digit  decimal  number  [00-99].  For  example,  93. 

%Y  Year  with  century  as  a  four-digit  decimal  number  [1970-2037].  For  example,  1994. 

%Z  Time  zone  name  (or  no  characters  if  time  zone  cannot  be  determined).  For  example,  PST. 

%%  The  %  character. 

Obsolescent  Directives 

The  following  directives  are  provided  for  backward  compatibility.  It  is  recommended  that  the  preceding 
directives  be  used  instead. 

%D  Date  in  usual  U.S.  format.  For  example,  01/12/94 .  Use  %x  or  %m/%d/%y  instead. 

%F  Full  month  name.  For  example,  January.  Use%B  instead. 

%h  Abbreviated  month  name.  For  example,  Jan.  Use%b  instead. 

%r  Time  in  12-hour  U.S.  format.  For  example,  07  :  45  :  58  PM.  Use  "%I:%M:%S  %p"  instead. 

%T  Time  in  24-hour  U.S.  format.  For  example,  19  :  45  :  58  .  Use  %X  or  %H:  %M:  %S  instead. 

%z  Time  zone  name  (or  no  characters  if  time  zone  cannot  be  determined).  For  example,  PST.  Use 
%Z  instead. 

Modified  Formatting  Directives 

Some  Formatting  Directives  can  be  modified  by  the  E  and  O  modifier  characters  to  indicate  a  different  for- 
mat or  specification  for  the  language  specified  in  the  LC_TIME  environment  variable. 

If  the  corresponding  keyword  (era,  era_year,  era_d_fmt,  and  alt_digit)  is  not  specified  or  not 
supported,  the  unmodified  field  descriptor  value  is  used.  The  command 

LC_ALL=  language  locale  -ck  era  era_year  era_d_fmt  alt_digit 

displays  the  keywords  and  their  values  in  the  specified  language  (see  locale(l)). 
%Ec        Alternate  appropriate  date  and  time  representation. 
%EC        The  name  of  the  base  year  in  alternate  representation. 
%Ex        Alternate  date  representation. 

%Ey        Offset  from  %EC  (year  only)  in  the  alternate  representation. 

%EY        Full  alternate  year  representation. 

%Od        Day  of  month  using  the  alternate  numeric  symbols. 

%Oe        Day  of  month  using  the  alternate  numeric  symbols  with  leading  space-character  fill  if  appli- 
cable. 

%OH        Hour  (24-hour  clock)  using  the  alternate  numeric  symbols. 
%Ol        Hour  (12-hour  clock)  using  the  alternate  numeric  symbols. 
%Om        Month  using  the  alternate  numeric  symbols. 
%OM        Minutes  using  the  alternate  numeric  symbols. 
%OS        Seconds  using  the  alternate  numeric  symbols. 

%OU        Week  number  of  the  year  (Sunday  is  the  first  day  of  the  week)  using  the  alternate  numeric 
symbols. 

%Ow        Weekday  as  number  using  the  alternate  numeric  symbols  (Sunday=0). 

%OW        Weekday  number  of  the  year  (Monday  is  the  first  day  of  the  week)  using  the  alternate 
numeric  symbols. 
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%0y        Year  (offset  from  %C)  in  alternate  representation. 

Field  Width  and  Precision 

An  optional  field  width  and  precision  specification  can  immediately  follow  the  initial  %  of  a  formatting  direc- 
tive in  the  foil  owing  order: 

[-  |  0]width  The  decimal  digit  string  width  specifies  a  minimum  field  width  in  which  the  result  of  the 
conversion  is  right-  or  I  eft -justified.  The  default  is  right-justified  with  space  padding  on 
the  left.  If  the  string  starts  with  the  result  is  I  eft -justified  with  space  padding  on  the 
right.  If  the  string  starts  with  "0",  the  result  is  right-justified  and  padded  with  zeros  on 
the  left. 

.  prec  The  decimal  digit  string  prec  specifies  the  minimum  number  of  digits  to  appear  for  the  d, 
H,  I,  j,  m,  M,  o,  S,  U,  w,  W,  y,  and  Y  numeric  directives.  If  a  directive  supplies  fewer 
digits  than  specified  by  the  precision,  it  will  be  expanded  with  leading  zeros. 

prec  specifies  the  maxi  mum  number  of  characters  to  be  used  from  the  a,  A,  b,  B,  c,  D,  E, 
F,  h,  n,  N,  p,  r,  t,  T,  x,  X,  z,  Z,  and  %  text  directives.  If  a  directive  supplies  more  char- 
acters than  specified  by  the  precision,  excess  characters  are  truncated  on  the  right. 

If  no  field  width  or  precision  is  specified  for  ad,  H,  I,  m,  M,  S,  U,  W,  or  y  directive,  the  default  is  .  2;  for  the 
j  directive,  the  default  is  .  3;  for  Y,  the  default  is  .  4;  for  w,  the  default  is  .  1. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  the  bytes  within  the  format  string  as  single-  and/or  multi-byte 
characters. 

LC_NUMERIC  determines  the  characters  used  to  form  numbers  for  those  directives  that  produce  numbers 
in  the  output.  The  characters  used  are  those  defined  by  alt_digit  (see  locale(l)  and  ALT_DIGIT  in 
langinfo(5)). 

LC_TIME  determines  the  content  (for  example,  the  weekday  names  produced  by  the  %a  directive)  and  for- 
mat (for  example,  the  current  time  representation  produced  by  the  %X  directive)  of  date  and  time  strings 
output  by  the  date  command. 

LC_ME S SAGE S  determines  the  language  in  which  messages  (other  than  the  date  and  time  strings)  are 
displayed. 

If  LC_CTYPE,  LC_NUMERIC,  LC_TIME,  or  LC_ME S SAGE S  is  not  specified  or  is  null,  it  defaults  to  the 
value  of  LANG. 

If  LANG  is  not  specified  or  is  null,  it  defaults  to  C  (see  lang(5)). 

If  any  internationalization  variable  contains  an  invalid  setting,  all  internationalization  variables  default  to 
C  (see environ (5)). 

TZ  determines  the  conversion  between  the  system  time  in  UTC  and  the  time  in  the  user's  local  time  zone. 
See  environ(5)  and  tztab(4).  TZ  also  determines  the  content  (that  is,  the  time-zone  name  produced  by  the 
%z  and  %Z  directives)  of  date  and  time  strings  output  by  the  date  command. 

If  TZ  is  not  set  or  is  set  to  the  empty  string,  its  default  value  is  EST5EDT. 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Thefollowing  messages  may  be  displayed. 

bad  conversion 

The  date/time  specification  is  syntactically  incorrect.  Check  it  against  the  usage  and  for  the 
correct  range  of  each  of  the  digit-pairs. 

bad  format  character  -  c 
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Thecharacter  c  is  not  a  valid  format  directive,  field  width  specifier,  or  precision  specifier. 

do  you  really  want  to  run  time  backwards? [yes/no] 

The  date/time  you  specified  is  earlier  than  the  current  clock  value.  Type  yes  (or  the  equivalent 
for  your  locale)  to  set  the  clock  backwards;  anything  else  to  cancel  the  command. 

no  permission 

You  need  thesuperuser  privilege  to  change  the  date. 

EXAMPLES 

Date  in  Different  Languages 

Display  the  date.  In  this  example,  the  TZ  environment  variable  contains  PST8PDT,  and  the  language 
environment  variables  are  set  as  noted. 

date  ->  Fri  Aug  20  15:03:37  PDT  1993     <-  C  (default) 

date  -u  ->  Fri  Aug  20  22:03:37  UTC  1993     <-  C  (default) 

date  ->  Fri,  Aug  20,   1993  03:03:37  PM  <-  en_US .  roman8  (U.S.English) 

date  ->  Fri.   20  Aug,    1993  03:03:37  PM  <-  en_GB .  roman8  (U.K.English) 

date  ->  20/08/1993  15.47.47  <-  pt_PT .  roman8  (Portuguese) 

Set  Date 

Set  the  date  to  Oct  8,  12:45  a.m. 

date  10080045 
Display  Formatted  Date 

Display  the  current  date  and  time  using  a  format.  Note  the  use  of  quotation  marks  due  to  the  blanks  in  the 
format. 

date   "+DATE:    %m/%d/%y%nTIME :  %H:%M:%S" 

The  output  resembles  the  following: 

DATE:  10/08/87 
TIME:  12:45:05 

Display  Formatted  Date  Using  Local  Language  Conversion 

With  the  date  as  set  in  the  "Set  Date"  example  above  and  LC_TIME  set  to  de_De .  roman8  (German): 

date  +'%-4.4h  %2 . Id  %H:%M' 
generates  output  si  mi  I  ar  to: 
Okt       8  12:45 

where  the  month  field  is  four  characters  long,  flush-left,  and  space-padded  on  the  right  if  the  month  name 
is  shorter  than  four  characters.  The  day  field  is  two  characters  long,  with  leading  zeros  suppressed. 

WARNINGS 

The  former  HP-UX  format  directiveA  has  been  changed  tow  for  ANSI  compatibility. 

Changing  the  date  while  the  system  is  running  in  multiuser  mode  should  be  avoided  to  prevent  disrupting 
user-scheduled  and  time  sensitive  programs  and  processes.  Also,  changing  the  date  can  cause  make(l)  and 
the  SCCS  and  cron(livi)  subsystems  to  behave  in  an  unexpected  manner.  The  cron  daemon  should  be 
killed  prior  to  setting  the  date  backwards,  then  restarted.  SCCS  files  should  be  checked  with  theval  com- 
mand (seeval(l))  if  deltas  have  been  made  while  the  clock  was  wrongly  set. 

Thefollowing  formatting  directives  may  bedeleted  from  future  releases:  %E,  %F,  %o,  %z. 

Currently,  the  maximum  date  supported  isDecember  31,  2037  23:59:00  UTC. 

AUTHOR 

date  was  developed  by  AT&T  and  HP. 

FILES 

/ var / adm/ wtmp 
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SEE  ALSO 

locale(l),  stime(2),  ctime(3C),  strftime(3C),  tztab(4),  environ(5),  lang(5),  langinfo(5). 

STANDARDS  CONFORMANCE 

date:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

dc  -  desk  calculator 

SYNOPSIS 

dc  [file] 

DESCRIPTION 

dc  is  an  arbitrary  precision  arithmetic  package.  Ordinarily  it  operates  on  decimal  integers,  but  one  may 
specify  an  input  base,  output  base,  and  a  number  of  fractional  digits  to  be  maintained.  (See  bc(l),  a  prepro- 
cessor for  dc  that  provides  infix  notation  and  a  C-like  syntax  that  implements  functions,  be  also  pro- 
vides reasonable  control  structures  for  programs.)  The  overall  structure  of  dc  is  a  stacking  (reverse  Pol- 
ish) calculator.  If  an  argument  is  given,  input  is  taken  from  that  file  until  its  end,  then  from  the  standard 
input.  An  end  of  file  on  standard  input  or  the  q  command  stop  dc.  Thefollowing  constructions  are  recog- 
nized: 

number  The  value  of  the  number  is  pushed  on  the  stack.  A  number  is  an  unbroken  string  of 

the  digits  0-9  or  A-F.  It  can  be  preceded  by  an  underscore  (_)  to  input  a  negative 
number.  Numbers  can  contain  decimal  points. 

+  -/*%" 

The  top  two  values  on  the  stack  are  added  (+),  subtracted  (-),  multiplied  (*),  divided 
(/),  remaindered  (%),  or  exponentiated  C).  The  two  entries  are  popped  off  the  stack; 
the  result  is  pushed  on  the  stack  in  their  place.  Any  fractional  part  of  an  exponent  is 
ignored  and  a  warning  generated.  The  remainder  is  calculated  according  to  the 
current  scale  factor;  it  is  not  the  integer  modulus  function.  7  %  3  yields  .1  (one 
tenth)  if  scale  is  1  because  7  /  3  is  2.3  with  .1  as  the  remainder. 

sx  The  top  of  the  stack  is  popped  and  stored  into  a  register  named  x,  where  x  can  be  any 

character.  If  the  s  is  capitalized,  x  is  treated  as  a  stack  and  the  value  is  pushed  on  it. 

lx  The  value  in  register  x  is  pushed  on  the  stack.  Register  x  is  not  altered.  All  registers 

start  with  zero  value.  If  the  1  is  capitalized,  register  x  is  treated  as  a  stack  and  its 
top  value  is  popped  onto  the  main  stack. 

d  Thetop  valueon  thestack  is  duplicated. 

p  The  top  value  on  the  stack  is  printed.  The  top  value  remains  unchanged.    P  inter- 

prets thetop  of  the  stack  as  an  ASCII  string,  removes  it,  and  prints  it. 

f  All  values  on  the  stack  are  printed. 

q  exits  the  program.  If  executing  a  string,  the  recursion  level  is  popped  by  two.  If  qis 

capitalized,  the  top  value  on  the  stack  is  popped  and  the  string  execution  level  is 
popped  by  that  value. 

x  treats  the  top  element  of  the  stack  as  a  character  string  and  executes  it  as  a  string  of 

dc  commands. 

X  replaces  the  number  on  the  top  of  the  stack  with  its  scale  factor. 

[ ...  ]  puts  the  bracketed  ASCII  string  onto  the  top  of  the  stack.  Strings  can  be  nested  by 

using  nested  pairs  of  brackets. 

<x      >x  =x 
!<x       !>x  !=x 

The  top  two  elements  of  the  stack  are  popped  and  compared.  Register  x  is  evaluated 
if  they  obey  the  stated  relation. 

v  Replaces  the  top  element  on  the  stack  by  its  square  root.  Any  existing  fractional  part 

of  the  argument  istaken  into  account,  but  otherwise  the  scalefactor  is  ignored. 

!  I  nterprets  the  rest  of  the  line  as  an  hp-ux  system  command  (unless  the  next  charac- 

ter is  <,  >,  or  =,  in  which  case  appropriate  relational  operator  above  is  used). 

c  All  values  on  thestack  are  popped. 

i  Thetop  valueon  the  stack  is  popped  and  used  as  the  number  radix  for  further  input. 

I  pushes  the  i  nput  base  on  the  top  of  the  stack. 
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o 
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Z 
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;  and 


The  top  value  on  the  stack  is  popped  and  used  as  the  number  radix  for  further  output. 
See  below  for  notes  on  output  base. 

pushes  the  output  base  on  the  top  of  the  stack. 

the  top  of  the  stack  is  popped,  and  that  value  is  used  as  a  non-negative  scale  factor: 
the  appropriate  number  of  places  are  printed  on  output,  and  maintained  during  multi- 
plication, division,  and  exponentiation.  The  interaction  of  scalefactor,  input  base,  and 
output  base  will  be  reasonable  if  all  are  changed  together. 

pushes  the  scale  factor  on  the  top  of  the  stack. 

The  stack  level  is  pushed  onto  the  stack. 

replaces  the  number  on  the  top  of  the  stack  with  its  length. 

A  line  of  input  istaken  from  the  input  source  (usuallythe  terminal)  and  executed. 

Used  by  be  for  array  operations. 

Generates  debugging  output  for  dc  itself. 


The  input  base  may  be  any  number,  but  only  the  digits  0-9  and  A-F  are  availablefor  input,  thus  limiting 
the  usefulness  of  bases  outside  the  range  1-16.  All  16  possible  digits  may  be  used  in  any  base;  they  always 
take  their  conventional  values. 

The  output  base  may  be  any  number.  Bases  in  the  range  of  2-16  generate  the  "usual"  results,  with  the 
letters  A-F  representing  the  values  from  10  through  16.  Bases  0  and  1  generate  a  string  of  Is  whose  length 
is  the  value  of  the  number.  Base  -1  generates  a  similar  string  consisting  of  ds.  Other  bases  have  each 
"digit"  represented  as  a  (multi-digit)  decimal  number  giving  the  ordinal  of  that  digit.  Each  "digit"  is  signed 
for  negative  bases.  "Digits"  are  separated  by  spaces.  Given  the  definition  of  output  base,  the  command  Op 
always  yields  "10"  (in  a  representation  appropriate  to  the  base);  Ol-p  yields  useful  information  about  the 
output  base. 

DIAGNOSTICS 

x  is  unimplemented       Where  x  is  an  octal  number. 

stack  empty  There  are  insufficient  elements  on  the  stack  to  do  what  was  asked. 

Out  of  space  Thefree  list  is  exhausted  (too  many  digits). 

Out  of  headers  Too  many  numbers  are  being  kept  around. 

Out  of  pushdown  Too  many  items  are  on  the  stack. 

Nesting  Depth  There  are  too  many  levels  of  nested  execution. 

EXAMPLES 

This  example  prints  the  first  ten  values  of  n!  (n  factorial): 


[lal+dsa*plalO>y] sy 

Osal 

lyx 


SEE  ALSO 

bc(l). 

DC:  An  I  nteractive  Desk  Calculator  tutorial  in  Number  Processing  Users  Guide. 
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NAME 

dd  -  convert,  reblock,  translate,  and  copy  a  (tape)  file 

SYNOPSIS 

dd  [option=value]  ... 

DESCRIPTION 

dd  copies  the  specified  input  file  to  the  specified  output  file  with  possible  conversions.  The  standard  input 
and  output  are  used  by  default.  I  nput  and  output  block  size  can  be  specified  to  take  advantage  of  raw  phy- 
sical I/O.  Upon  completion,  dd  reports  the  number  of  whole  and  partial  input  and  output  records. 

Options 

dd  recognizes  the  following  option=value  pairs: 

if=file  I  nput  file  name;  default  is  standard  input. 

of=file  Output  file  name;  default  is  standard  output.  The  output  file  is  created  using  the 

same  owner  and  group  used  by  creat  ( )  . 

ibs=n  I  nput  block  size  is  n  bytes;  default  is  512. 

obs=n  Output  block  size  is  n  bytes;  default  is  512. 

bs=n  Set  both  input  and  output  block  size  to  the  same  size,  superseding  ibs  and  obs. 

This  option  is  particularly  efficient  if  no  conversion  (conv  option)  is  specified,  because 
no  in-core  copy  is  necessary. 

cbs=n  Conversion  buffer  size  is  n  bytes. 

skip=n         Skip  n  input  blocks  before  starting  copy. 

iseek=n       Skip  n  input  blocks  before  starting  copy.  (This  is  an  aliasfor  the  skip  option.) 
seek=n         Skipn  blocks  from  beginning  of  output  file  before  copying. 

oseek=n       Skip  n  blocks  from  beginning  of  output  file  before  copying.  (This  is  an  alias  for  the 
seek  option.) 

count = n        C  opy  on  I  y  n  i  n  put  bl  ocks. 

files=n       Copy  and  concatenate  n  input  files.  This  option  should  be  used  only  when  the  input 
file  is  a  magnetic  tape  device. 

conv= value  [,  value ...] 

Where  values  are  comma-separated  symbols  from  the  foil  owing  list. 

ascii  Convert  EBCDIC  to  ASCI  I. 

ebcdic  Convert  ASCI  I  to  EBCDIC. 

ibm  Convert  ASCII  toEBCDIC  usingan  alternate  conversion  table. 

Theascii,  ebcdic,  and  ibm  values  are  mutually  exclusive. 


block 


unblock 


lease 


Convert  each  newline-terminated  or  end-of-file-terminated  input 
record  to  a  record  with  a  fixed  length  specified  by  cbs.  Any  new- 
line  character  is  removed,  and  space  characters  are  used  to  fill  the 
block  to  size  cbs.  Lines  that  are  longer  than  cbs  are  truncated; 
the  number  of  truncated  lines  (records)  is  reported  (see  DIAGNOS- 
TICS below). 

Theblock  and  unblock  values  are  mutually  exclusive. 

Convert  fixed-length  input  records  to  variable-length  records.  For 
each  input  record,  cbs  bytes  are  read,  trailing  space  characters 
are  deleted,  and  a  newline  character  isappended. 

Map  upper-case  input  characters  to  the  corresponding  lower-case 
characters. 

The  lease  and  ucase  values  are  mutually  exclusive. 

Map  lower-case  input  characters  to  the  corresponding  upper-case 
characters. 
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swab  Swap  every  pair  of  input  bytes. 

noerror  Do  not  stop  processing  on  an  input  error.  If  the  sync  conversion 

symbol  is  also  specified,  missing  input  is  replaced  with  null  bytes 
and  processed  normally;  otherwise,  the  input  block  is  omitted  from 
the  output. 

notrunc  Do  not  truncate  existing  output  file.  Blocks  in  the  output  file  not 

overwritten  by  this  invocation  of  dd  are  preserved. 

sync  Pad  every  input  block  to  size  ibs.  Ifblockor  unblock  is  also 

specified,  pad  with  space  characters;  otherwise,  pad  with  null 
bytes. 

Where  sizes  are  required,  n  indicates  a  numerical  value  in  bytes.  Numbers  can  be  specified  using  the 
forms: 

n  for  n  bytes 

nk  for  n  Kbytes  (n  x  1024), 

nb  for  n  blocks  (n  x  512),  or 

nw  for  n  words  (n  x  2). 

To  indicatea  product,  use x  to  separate  number  pairs. 

The  cbs  option  is  used  when  block,  unblock,  ascii  or  ebcdic  conversion  is  specified.  In  case  of 
ascii,  cbs  characters  are  placed  into  the  conversion  buffer,  converted  to  ASCII,  trailing  blanks  are 
trimmed,  and  a  newline  is  added  before  sending  the  line  to  the  output.  In  case  of  ebcdic,  ASCII  charac- 
ters are  read  into  the  conversion  buffer,  converted  to  EBCDIC,  and  blanks  are  added  to  make  up  an  output 
block  of  size  cbs. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

Envi  ronment  Variables 

The  foil  owing  environment  variables  affect  execution  of  dd: 

LANG  determines  the  locale  when  LC_ALL  and  a  corresponding  variable  (beginning  with  LC_)  do  not 
specify  a  locale. 

LC_ALL  determines  the  locale  used  to  override  any  values  set  by  LANG  or  any  environment  variables 
beginning  with  LC_. 

The  LC_CTYPE  variable  determines  the  locale  for  the  interpretation  of  sequences  of  bytes  of  text  data  as 
characters  (single-byte/multi-byte  characters,  upper-case/lower-case  characters). 

The  LC_ME S SAGE S  variable  determines  the  language  in  which  messages  are  written. 

RETURN  VALUE 

Exit  values  are: 

0       Successful  completion. 
>0       Error  condition  occurred. 

DIAGNOSTICS 

Upon  completion,  dd  reports  the  number  of  input  and  output  records: 

f+p  records  in         Number  of  full  and  partial  blocks  read, 
f+p  records  out       Number  of  full  and  partial  blocks  written. 

When  conv=block  is  specified  and  there  is  at  least  one  truncated  block,  the  number  of  truncated  records 
is  also  reported: 

n  truncated  records 
EXAMPLES 

Read  an  EBCDIC  tape  blocked  ten  80-byte  EBCDIC  card  images  per  block  into  an  ASCI  I  file  named  x: 
dd  if=/dev/rmt/c0t0d0BEST  of=x  ibs=800  cbs=80  conv=ascii , lease 
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Note  the  use  of  the  raw  magnetic  tape  device  file,  dd  is  especially  suited  to  I/O  on  raw  physical  devices 
because  it  allows  reading  and  writing  in  arbitrary  block  sizes. 

WARNINGS 

Some  devices,  such  as  1/2-inch  magnetic  tapes,  are  incapable  of  seeking.  Such  devices  may  be  positioned 
prior  to  running  dd  by  using  mt(l)  or  some  other  appropriate  command.  The  skip,  seek,  iseek  and 
oseek  options  do  work  for  such  devices.  However,  skipping  blocks  using  these  options  is  slow  on  devices 
that  cannot  seek,  si  nee  the  blocks  must  actually  be  read  to  get  to  the  desired  position  on  the  tape. 

ASCII  and  EBCDIC  conversion  tables  are  taken  from  the  256-character  ACM  standard,  Nov,  1968.  The 
ibm  conversion,  while  less  widely  accepted  as  a  standard,  corresponds  better  to  certain  IBM  print  train 
conventions.  There  is  no  universal  solution. 

Newline  characters  are  inserted  only  on  conversion  to  ASCII;  padding  is  done  only  on  conversion  to 
EBCDIC.  These  should  be  separate  options. 

If  if  or  of  refers  to  a  raw  disk,  bs  should  always  be  a  multiple  of  the  sector  size  of  the  disk.  By  default, 
bs  is  512  bytes.  If  the  sector  size  of  the  disk  is  different  from  512  bytes,  bs  should  be  specified  using  a 
multiple  of  sector  size.  The  character  special  (raw)  device  file  should  always  be  used  for  devices. 

It  is  entirely  up  to  the  user  to  insure  there  is  enough  room  in  the  destination  file,  file  system  and/or  device 
to  contain  the  output  sincedd  cannot  pre-determine  the  required  space  after  conversion. 


SEE  ALSO 

cp(l),  mt(l),  tr(l),  disk(7),  mt(7). 

STANDARDS  CONFORMANCE 

dd:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

delta  -  make  a  delta  (change)  to  an  SCCS  file 
SYNOPSIS 

delta  [-r  SID]  [-s]  [-n]  [-g  list]  [-m  mrlist]  [-y  comment]  [-p]  files 
DESCRIPTION 

The  delta  command  is  used  to  permanently  introduce  into  the  named  SCCS  file  changes  that  were  made 
to  the  file  retrieved  by  get  (called  the  g-file,  or  generated  file).  Seeget(l). 

delta  makes  a  delta  to  each  named  SCCS  file.  If  a  directory  is  named,  delta  behaves  as  though  each  file 
in  the  directory  was  specified  as  a  named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name 
does  not  begin  with  .s)  and  unreadable  files  are  silently  ignored.  If  a  name  of  -  is  given,  the  standard 
input  is  read  (see  warnings).  Each  line  of  the  standard  input  is  taken  to  be  the  name  of  an  SCCS  file  to  be 
processed. 

delta  may  issue  prompts  on  the  standard  output,  depending  upon  certain  options  specified  and  flags  (see 
admin  (1))  that  may  be  present  in  the  SCCS  file  (seethe  -m  and  -y  options  below). 

Options 

Option  arguments  apply  independently  to  each  named  file. 

-rSiD  Uniquely  identifies  which  delta  is  to  be  made  to  the  SCCS  file.  Use  of  this  option  is 

necessary  only  if  two  or  more  outstanding  gets  for  editing  (get  -e)  on  the  same 
SCCS  file  were  done  by  the  same  person  (login  name).  TheSiD  value  specified  with 
the  -r  option  can  be  either  the  SID  specified  on  the  get  command  line  or  the  SID  to 
be  made  as  reported  by  the  get  command  (see  get(l)).  A  diagnostic  results  if  the 
specified  SID  is  ambiguous,  or,  if  necessary  and  omitted  on  the  command  line. 

-s  Suppresses  issuing,  on  the  standard  output,  of  the  created  delta's  SID  as  well  as  the 

number  of  lines  inserted,  deleted  and  unchanged  in  the  SCCS  file. 

-n  Specifies  retention  of  the  edited  g-file  (normally  removed  at  completion  of  delta  pro- 

cessing). 

-glist  Specifies  a  list  (see  get(l)  for  the  definition  of  list)  of  deltas  which  are  to  be  ignored 

when  the  file  is  accessed  at  the  change  level  (SID)  created  by  this  delta. 

-m[mrlist]       If  the  SCCS  file  has  the  v  flag  set  (see  admin (1)),  a  Modification  Request  (MR)  number 
must  be  supplied  as  the  reason  for  creating  the  new  delta. 

If  -m  is  not  used  and  the  standard  input  is  a  terminal,  the  prompt  MRs?  is  issued  on 
the  standard  output  before  the  standard  input  is  read.  If  the  standard  input  is  not  a 
terminal,  no  prompt  is  issued.  The  MRs?  prompt  always  precedes  the  comments? 
prompt  (see  the -y  option). 

mrs  in  a  list  are  separated  by  blanks  and/or  tab  characters.  An  unescaped  new-line 
character  terminates  the  MR  list. 

Note  that  if  the  v  flag  has  a  value  (see  admin(l)),  it  is  assumed  to  be  the  name  of  a 
program  (or  shell  procedure)  that  is  to  validate  the  correctness  of  the  MR  numbers.  If 
a  non-zero  exit  status  is  returned  from  the  MR  number-validation  program,  delta 
assumes  that  theMR  numbers  were  not  all  valid  and  terminates. 

-y[comment]    Arbitrary  text  used  to  describe  the  reason  for  making  the  delta.  A  null  string  is  con- 
sidered a  valid  comment. 

If  -y  is  not  specified  and  the  standard  input  is  a  terminal,  the  prompt  comments? 
is  issued  on  the  standard  output  before  the  standard  input  is  read.  If  the  standard 
input  is  not  a  terminal,  no  prompt  is  issued.  An  unescaped  new-line  character  ter- 
minates the  comment  text. 

-p  Causes  delta  to  print  (on  the  standard  output  in  a  diff(l)  format)  the  SCCS  file 

differences  before  and  after  the  delta  is  applied. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single- and/or  multi-byte  characters. 
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LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set 
to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  vari- 
able contains  an  invalid  setting,  delta  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Usesccshelp(l)  for  explanations. 

WARNINGS 

sees  files  can  beany  length,  but  the  number  of  lines  in  the  text  file  itself  cannot  exceed  99999  lines. 

Lines  beginning  with  an  ASCII  SOH  character  (octal  001)  cannot  be  placed  in  the  sees  file  unless  the  SOH  is 
escaped.  This  character  has  special  meaning  to  sees  (see  sccsfile(4))  and  will  causean  error. 

A  get  of  many  sees  files,  followed  by  a  delta  of  those  files,  should  be  avoided  when  the  get  generates  a 
large  amount  of  data.  Instead,  multipleget/delta  sequences  should  be  used. 

If  the  standard  input  (-)  is  specified  on  the  delta  command  line,  the  -m  (if  necessary)  and  -y  options 
must  also  be  present.  Omission  of  these  options  causes  an  error. 

Comments  can  be  of  multiple  lines.  The  maximum  length  of  the  comment  (total  length  of  all  comment 
lines)  cannot  exceed  1024  bytes.  No  line  in  a  comment  should  have  a  length  of  more  than  1000  bytes. 

FILES 

All  of  the  auxiliary  files  listed  below,  except  for  the  g-file,  are  created  in  the  same  directory  as  the  s-file  (see 
get(l)).  The  g-file  is  created  in  the  user's  working  directory. 


g-file  Existed  before  the  execution  of  delta;  removed  after  completion  of  delta 

(unless  -n  was  specified). 

p-file  Existed  before  the  execution  of  delta;  may  exist  after  completion  of  delta, 

q-file  Created  during  the  execution  of  delta;  removed  after  completion  of  delta, 

x-file  Created  during  the  execution  of  delta;  renamed  to  sees  file  after  completion  of 

delta. 

z-file  Created  during  the  execution  of  delta;  removed  during  the  execution  of  delta, 

d-file  Created  during  the  execution  of  delta;  removed  after  completion  of  delta. 


/usr/bin/bdif  f  Program  to  compute  differences  between  the  file  retrieved  by  get  and  the  g-file. 
SEE  ALSO 

admin(l),  bdiff(l),  cdc(l),  get(l),  sccshelp(l),  prs(l),  rmdel(l),  sccsfile(4). 

STANDARDS  CONFORMANCE 

delta:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

deroff  -  remove  nroff,  tbl,  and  neqn  constructs 

SYNOPSIS 

deroff  [-mx]  [-w]  [-i]  [file  ...] 

DESCRIPTION 

deroff  reads  each  file  in  sequence  and  removes  all  nroff  requests,  macro  calls,  backslash  constructs, 
neqn  constructs  (between  .eq  and  .en  lines,  and  between  delimiters  —  see  neqn(l)),  and  tbl  descrip- 
tions (see  tbl  (1)),  replacing  them  with  white  space  (blanks  and  blank  lines),  and  writes  the  remainder  of  the 
file  on  the  standard  output,  deroff  follows  chains  of  included  files  ( .  so  and  .nx  nrof  f  /trof  f  for- 
matter commands);  if  a  file  has  already  been  included,  a  .  so  naming  that  file  is  ignored  and  a  .nx  nam- 
ing that  file  terminates  execution.  If  no  input  file  is  given,  deroff  reads  the  standard  input. 

The  -m  option  can  be  followed  by  an  m,  s,  or  1.  The  -mm  option  causes  the  macros  be  interpreted  such 
that  only  running  text  is  output  (that  is,  no  text  from  macro  lines).  The  -ml  option  forces  the  —mm  option 
and  also  causes  deletion  of  lists  associated  with  the  mm  macros. 

If  the  -w  option  is  given,  the  output  is  a  word  list,  one  "word"  per  line,  with  all  other  characters  deleted. 
Otherwise,  the  output  follows  the  original,  with  the  deletions  mentioned  above.  In  text,  a  "word"  is  any 
multi -byte  character  string  or  any  string  that  contains  at  least  two  letters  and  is  composed  of  letters,  digits, 
ampersands  (&),  and  apostrophes  (' );  I  n  a  macro  call,  however,  a  "word"  is  a  multi -byte character  string  or 
a  string  that  begins  with  at  least  two  letters  and  contains  a  total  of  at  least  three  letters.  Delimiters  are 
any  characters  other  than  letters,  digits,  apostrophes,  and  ampersands.  Trailing  apostrophes  and  amper- 
sands are  removed  from  "words." 

If  the  -i  option  isspecified,  deroff  ignores  the  .so  and  .nx  nroff /trof  f  commands. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  and  filenames  as  single  and/or  multi-byte  characters. 
Note  that  multi-byte  punctuation  characters  are  not  recognized  when  using  the  -w  option. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  deroff  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi -byte  character  code  sets  are  supported. 

WARNINGS 

deroff  is  not  a  complete  nroff  interpreter;  thus  it  can  be  confused  by  subtle  constructs.  Most  such 
errors  result  in  too  much  rather  than  too  little  output. 

The  -ml  option  does  not  handlenested  lists  correctly. 
AUTHOR 

deroff  was  developed  by  the  University  of  California,  Berkeley. 

SEE  ALSO 

neqn(l),  nroff(l),  tbl(l). 
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NAME 

diff  -  differential  file  and  directory  comparator 
SYNOPSIS 

diff  [-C  n]  [-S  name]  [-Irs]  [-bcefhintw]  dirl  dir2 
diff  [-C  n]  [-S  name]  [-bcefhintw]  filel  file2 
diff  [-D  string]  [-biw]  filel  file2 

DESCRIPTION 

Comparing  Directories 

If  both  arguments  are  directories,  diff  sorts  the  contents  of  the  directories  by  name,  then  runs  the  regu- 
lar file  diff  algorithm  (described  below)  on  text  files  that  have  the  same  name  in  each  directory  but  are 
different.  Binary  files  that  differ,  common  subdirectories,  and  files  that  appear  in  only  one  directory  are 
listed.  When  comparing  directories,  the  following  options  are  recognized: 

-1  Long  output  format;  each  text  file  diff  is  piped  through  pr  to  paginate  it  (see  pr(l)). 

Other  differences  are  remembered  and  summarized  after  all  text  file  differences  are 
reported. 

-r  Applies  diff  recursively  to  common  subdirectories  encountered, 

-s  diff  reports  files  that  are  identical  but  otherwise  not  mentioned. 

-S  name    Starts  a  directory  diff  in  the  middleof  the  sorted  directory,  beginning  with  file  name. 

Comparing  Files 

When  run  on  regular  files,  and  when  comparing  text  files  that  differ  during  directory  comparison,  diff 
tells  what  lines  must  be  changed  in  the  files  to  bring  them  into  agreement,  diff  usually  finds  a  smallest 
sufficient  set  of  file  differences.  However,  it  can  be  misled  by  lines  containing  very  few  characters  or  by 
other  situations.  If  neither  filel  nor  file2  is  a  directory,  either  can  be  specified  as-,  in  which  case  the  stan- 
dard input  is  used.  If  filel  is  a  directory,  a  file  in  that  directory  whose  filename  is  the  same  as  the  filename 
of  file2  is  used  (and  vice  versa). 

There  are  several  options  for  output  format.  The  default  output  format  contains  lines  resembling  the  fol- 
lowing: 

nl  a  n3, n4 
nl,  n2  d  n3 
nl, n2  c  n3, n4 

These  lines  resemble  ed  commands  to  convert  filel  into  file2.  The  numbers  after  the  letters  pertain  to 
file2.  In  fact,  by  exchanging  a  for  d  and  reading  backwards  one  may  ascertain  equally  how  to  convert 
file2  into  filel.  As  in  ed,  identical  pairs  where  nl  =n2  or  n3  =n4  are  abbreviated  as  a  single  number. 

Following  each  of  these  lines  come  all  the  lines  that  are  affected  in  the  first  file  flagged  by  <,  then  all  the 
lines  that  are  affected  in  the  second  fileflagged  by  >. 

Except  for  -b,  -w,  -i,  or  -t  which  can  be  given  with  any  of  the  others,  the  foil  owing  options  are  mutually 
exclusive: 

-e  Produce  a  script  of  a,  c,  and  d  commands  for  the  ed  editor  suitable  for  recreating  file2 
from  filel.  Extra  commands  are  added  to  the  output  when  comparing  directories  with  -e, 
so  that  the  result  is  a  shell  script  for  converting  text  files  common  to  the  two  directories 
from  their  state  in  dirl  to  their  state  in  dir2  (see  sh-bourne(l) 

-f  Produce  a  script  similar  to  that  of  the  -e  option  that  is  not  useful  with  ed  but  is  more 
readable  by  humans. 

-n  Produce  a  script  similar  to  that  of  -e,  but  in  the  opposite  order,  and  with  a  count  of  changed 
lines  on  each  insert  or  delete  command.  This  is  the  form  used  by  rcsdiff  (see  rcsdiff(l)). 

-c  Produce  a  difference  list  with  3  lines  of  context,  -c  modifies  the  output  format  slightly: 
the  output  begins  with  identification  of  the  files  involved,  followed  by  their  creation  dates, 
then  each  change  separated  by  a  line  containing  about  twelve  asterisks  ( *  )s.  Lines  removed 
from  filel  are  marked  with  -,  and  lines  added  to  file2  are  marked  +.  Lines  that  change  from 
one  file  to  the  other  are  marked  in  both  files  with  with  ! .  Changes  that  lie  within  3  lines  of 
each  other  in  thefileare grouped  together  on  output. 
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-C  n      Output  format  similar  to  -c  but  with  n  lines  of  context. 

-h  Do  a  fast,  half-hearted  job.  This  option  works  only  when  changed  stretches  are  short  and 
well  separated,  but  can  be  used  on  files  of  unlimited  length. 

-D  string 

Create  a  merged  version  of  filel  and  file2  on  the  standard  output,  with  C  preprocessor  con- 
trols included  so  that  a  compilation  of  the  result  without  defining  string  is  equivalent  to  com- 
piling filel,  while  compiling  the  result  with  string  defined  is  equivalent  to  compiling  file2. 

-b         Ignore  trailing  blanks  (spaces  and  tabs)  and  treat  other  strings  of  blanks  as  equal. 

-w  I gnore  all  whitespace  (blanks  and  tabs).  For  example,  if  (  a  ==  b  )  and  if(a==b) 
are  treated  as  equal. 

-i         I  gnores  uppercase/lowercase  differences.  Thus  A  is  treated  the  same  as  a. 

-t  Expand  tabs  in  output  lines.  Normal  or  -c  output  adds  one  or  more  characters  to  the  front 
of  each  line.  Resulting  misalignment  of  indentation  in  the  original  source  lines  can  makethe 
output  listing  difficult  to  interpret.  Thisoption  preserves  original  source  file  indentation. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  set  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used. 

LC_CTYPE  determines  the  space  characters  for  the  diff  command,  and  the  interpretation  of  text  within 
file  as  single-  and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  any  internationalization  variable  contains  an  invalid  setting,  diff  and  diffh  behave  as  if  all  interna- 
tionalization variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported  with  the  exception  that  diff  and  diffh  do  not 
recognize  multi -byte  alternative  space  characters. 

RETURN  VALUE 

Upon  completion,  diff  returns  with  one  of  the  following  exit  values: 

0  No  differences  were  found. 

1  D  i  ff eren  ces  were  f ou  n  d . 
>1       An  error  occurred. 

EXAMPLES 

The  foil  owing  command  creates  a  script  file  script : 

diff  -e  xl  x2  >script 
w  is  added  to  the  end  of  the  script  in  order  to  save  the  file: 

echo  w  »  script 

The  script  file  can  then  be  used  to  create  the  file  x2  from  the  file  xl  using  the  editor  ed  in  the  following 
manner: 

ed  xl  <  script 

Thefollowing  command  produces  the  difference  output  with  2  lines  of  context  information  before  and  after 
the  line  that  was  different: 

diff  -C2  xl  x2 

Thefollowing  command  ignores  all  blanks  and  tabs  and  ignores  uppercase-lowercase  differences, 
diff  -wi  xl  x2 
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WARNINGS 


Editing  scripts  produced  by  the  -e  or  -f  option  are  naive  about  creating  lines  consisting  of  a  single  dot 
(.). 

When  comparing  directories  with  the  -b,  -w,  or  -i  options  specified,  dif  f  first  compares  the  files  in  the 
same  manner  as  cmp,  then  runs  the  diff  algorithm  if  they  are  not  equal.  This  may  cause  a  small 
amount  of  spurious  output  if  the  files  are  identical  except  for  insignificant  blank  strings  or 
uppercase/lowercase  differences. 

The  default  algorithm  requires  memory  allocation  of  roughly  six  times  the  size  of  the  file.  If  sufficient 
memory  is  not  availablefor  handling  large  files,  the  -h  option  or  bdiff  can  be  used  (see  bdiff(l)). 

With  other  options  if  sufficient  memory  is  not  available,  then  either  the  swap  or  maxdsiz  values  can  be 
increased. 

When  run  on  directories  with  the  -r  option,  diff  recursively  descends  sub-trees.  When  comparing  deep 
multi-level  directories,  more  memory  may  be  required  than  is  currently  available  on  the  system.  The 
amount  of  memory  required  depends  on  the  depth  of  recursion  and  the  size  of  the  files. 

AUTHOR 

diff  was  developed  by  AT&T,  the  University  of  California,  Berkeley,  and  HP. 


bdiff(l),  cmp(l),  comm(l),  diff3(l),  diffmk(l),  dircmp(l),  ed(l),  more(l),  nroff(l),  rcsdiff(l),  sccsdiff(l), 
sdiff(l),  terminfo(4). 

STANDARDS  CONFORMANCE 

diff:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 


FILES 


/usr/lbin/diffh 


used  by  -h  option 


SEE  ALSO 
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NAME 

diff 3  -  3-way  differential  file  comparison 

SYNOPSIS 

diff 3  [-exEX3]  filel  file2  file3 

DESCRIPTION 

diff  3  compares  three  versions  of  a  file,  and  prints  disagreeing  ranges  of  text  flagged  with  these  codes: 

====  all  three  files  differ 

====1  filel  is  different 

====2  file2  is  different 

====3  file3  is  different 

The  type  of  change  required  to  convert  a  given  range  of  a  given  file  to  some  other  is  indicated  in  one  of 
these  ways: 

f :  nla  Text  is  to  be  appended  after  line  number  nl  in  file  f ,  where  f  =  1,  2,  or  3. 

f :  nl,  n2c       Text  is  to  be  changed  in  the  range  line  nl  through  line  n2.  If  nl  =  n2,  the  range  can 
be  abbreviated  to  nl. 

The  original  contents  of  the  range  follows  immediately  after  a  c  indication.  When  the  contents  of  two  files 
are  identical,  the  contents  of  the  lower-numbered  file  is  suppressed. 

-e  dif f3  Produces  a  script  for  the  ed  editor  that  can  be  used  to  incorporate  into  filel  all 

changes  between  file2  and  file3  (see  ed(l));  i.e.,  the  changes  that  normally  would  be  flagged 

-x  Produces  a  script  to  incorporate  only  changes  flagged  ==== 

-3  Produces  a  script  to  incorporate  only  changes  flagged  ====3 

-E  Produces  a  script  that  will  incorporate  all  changes  between  file2  and  file3,  but  treat  overlap- 

ping changes  (that  is,  changes  that  would  be  flagged  with  ====  in  normal  listing) 
differently.  The  overlapping  lines  in  both  files  will  be  inserted  by  the  edit  script  bracketed 
by  «««  and  »»»  lines. 

-X  Produces  a  script  that  will  incorporate  only  changes  flagged  ====  ,  but  treat  these 

changes  in  the  manner  of  -E  option. 

The  foil  owing  command  applies  the  resulting  script  to  filel. 

(cat  script;   echo  'l,$p')    |  ed  -  filel 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

WARNINGS 

Text  lines  that  consist  of  a  single  period  ( . )  defeat  -e. 
Files  longer  than  64K  bytes  do  not  work. 

FILES 

/var/tmp/d3* 

/ usr/ lbin/ dif f 3prog 

SEE  ALSO 

diff(l). 
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NAME 

diffmk  -  mark  changes  between  two  different  versions  of  a  file 

SYNOPSIS 

diffmk  prevfile  currfile  markfile 

DESCRIPTION 

diffmk  compares  the  previous  version  of  a  file  with  the  current  version  and  creates  a  file  that  includes 
nroff/troff  "change  mark"  commands,  prevfile  is  the  name  of  the  previous  version  of  the  file  and 
currfile  is  the  name  of  the  current  version  of  the  file,  diffmk  generates  markfile  which  contains  all  the 
lines  of  the  currfile  plus  inserted  formatter  "change  mark"  (,mc)  requests.  When  markfile  is  formatted, 
changed  or  inserted  text  is  shown  by  a  |  character  at  the  right  margin  of  each  line.  The  position  of  deleted 
text  is  shown  by  a  single  *. 

If  the  characters  |  and  *  are  inappropriate,  a  copy  of  diffmk  can  be  edited  to  change  them  because 
diffmk  is  a  shell  script. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

A  typical  command  line  for  comparing  two  versions  of  an  nroff/troff  file  and  generating  a  file  with  the 
changes  marked  is: 

diffmk  prevfile  currfile  markfile;    nroff  markfile    |  pr 

diffmk  can  also  be  used  to  produce  listings  of  C  (or  other)  programs  with  changes  marked.  A  typical  com- 
mand line  for  such  use  is: 

diffmk  prevfile . c  currfile. c  markfile. c;    nroff  macs  markfile. c    |  pr 

where  the  file  macs  contains: 

.pi  1 
.11  77 
.nf 
.eo 

The  .  11  request  can  specify  a  different  line  length,  depending  on  the  nature  of  the  program  being  printed. 
The  .eo  request  is  probably  needed  only  for  C  programs. 

WARNINGS 

Aesthetic  considerations  may  dictate  manual  adjustment  of  some  output. 

diffmk  does  not  differentiate  between  changes  in  text  and  changes  in  formatter  request  coding.  Thus,  file 
differences  involving  only  formatting  changes  (such  as  replacing  .  sp  with  .  sp  2  in  a  text  source  file)  with 
no  change  i  n  actual  text  can  produce  change  marks. 

Although  unlikely,  certain  combinations  of  formatting  requests  can  cause  change  marks  to  either  disappear 
or  to  mark  too  much.  Manual  intervention  may  be  required  because  the  subtleties  of  various  formatting 
macro  packages  and  preprocessors  is  beyond  the  scope  of  diffmk.  tbl  cannot  tolerate  .mc  commands  in 
its  input  (see  tbl(l)),  so  any  .mc  request  that  would  appear  inside  a  .  TS  range  is  silently  deleted.  The 
script  can  be  changed  if  this  action  is  inappropriate,  or  diffmk  can  be  run  on  two  files  that  have  both  been 
run  through  the  tbl  preprocessor  before  any  comparisons  are  made. 

diffmk  uses  diff,  and  thus  has  the  same  limitations  on  file  size  and  performance  that  diff  may 
impose  (see  diff  (1)).  I  n  particular  the  performance  is  nonlinear  with  the  size  of  the  file,  and  very  large  files 
(well  over  1000  lines)  may  take  extremely  long  to  process.  Breaking  the  file  into  smaller  pieces  may  be 
advisable. 

diffmk  also  uses  the  ed(l)  editor.  If  the  file  is  too  large  for  ed,  ed  error  messages  may  be  embedded  in 
the  file.  Again,  breaking  the  file  into  smaller  pieces  may  be  advisable. 

SEE  ALSO 

diff(l),  nroff(l). 
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NAME 

dircmp  -  directory  comparison 

SYNOPSIS 

dircmp  [-d]  [-s]  [-wn  ]  dirl  dir2 

DESCRIPTION 

dircmp  examines  dirl  and  dir2  and  generates  various  tabulated  information  about  the  contents  of  the 
directories.  Sorted  listings  of  files  that  are  unique  to  each  directory  are  generated  for  all  the  options.  If  no 
option  is  entered,  a  sorted  list  is  output  indicating  whether  the  filenames  common  to  both  directories  have 
the  same  contents. 

-d  Compare  the  contents  of  files  with  the  same  name  in  both  directories  and  output  a  list  telling 
what  must  be  changed  in  the  two  files  to  bring  them  into  agreement.  The  list  format  is 
described  in  diff(l). 

-s       Suppress  messages  about  identical  files. 

-wn      Change  the  width  of  the  output  line  to  n  characters.  The  default  width  is  72. 

EXTERNAL  INFLUENCES 
Environment  Variables 

lc  collate  determines  the  order  in  which  the  output  is  sorted. 

If  LC_COLLATE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is 
used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid  setting,  dircmp  behaves  as 
if  all  internationalization  variables  are  set  to  "C"  (see  environ  (5)). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

Compare  the  two  directories  slate  and  sleet  and  produce  a  list  of  changes  that  would  make  the  direc- 
tories identical: 

dircmp  -d  slate  sleet 
WARNINGS 

This  command  is  likely  to  be  withdrawn  from  X/Open  standards.  Applications  using  this  command  might 
not  be  portableto  other  vendors'  systems.  As  an  alternative diff  -R  is  recommended. 

SEE  ALSO 

cmp(l),  diff(l). 

STANDARDS  CONFORMANCE 

dircmp:  SVID2,  SVID3,  XPG2,  XPG3 
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NAME 

dmpxlt  -  dump  iconv  translation  tables  to  a  readable  format 
SYNOPSIS 

/usr/bin/dmpxlt  [-f  outputfilename]  [inputfilename] 
DESCRIPTION 

dmpxlt  dumps  the  compiled  version  of  the  iconv  codeset  conversion  tables  into  an  ASCI  I -readable  for- 
mat that  can  be  modified  and  used  as  input  to  genxlt(l)  to  regenerate  the  tablefor  iconv(l). 

Options 

dmpxlt  recognizes  the  following  options: 

-f  output  filename     If  this  option  is  not  selected,  the  data  will  be  sent  to  standard  output. 

dmpxlt  will  create  an  output  file  in  the  prescribed  format,  giving  the  filecode  mapping  between  the  two 
code  sets,  which  can  be  edited  and  reused  by  genxlt(l)  to  create  new  tables  for  iconv(l).  The  entries  are  in 
hexadeci  mal. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  dmpxlt  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Singleand  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

The  foil  owing  are  exit  values: 

0       Successful  completion. 
>0       Error  condition  occurred. 

EXAMPLES 

This  example  creates  the  sourcefilegenxlt  input  from  the  table  roma8=iso81 : 

dmpxlt  -f  genxlt_input  /usr/lib/nls/iconv/tables/roma8=iso81 

FILES 

/usr/lib/nls/iconv/tables       All  tables  must  be  installed  in  this  directory. 
SEE  ALSO 

iconv(l),  genxlt(l),  iconv(3C),  environ(5),  lang(5). 
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NAME 

domainname-  set  or  display  name  of  Network  I  nformation  Service  domain 

SYNOPSIS 

domainname  [  nameofdomai  n  ] 

DESCRIPTION 

Network  Information  Service  (NIS)  uses  domain  names  to  refer  collectively  to  a  group  of  hosts.  Without  an 
argument,  domainname  displays  the  name  of  theNIS  domain.  Only  superuser  can  set  the  domain  name  by 
providing  nameofdomain.  The  domain  name  is  usually  set  in  the  configuration  file 
/etc/rc  .  conf  ig .  d/namesvrs,  by  setting  the NIS_DOMAIN  variable. 

DEPENDENCIES 

NIS  servers  use  the  NIS  domain  name  as  the  name  of  a  subdirectory  of  /var/yp.  Since  the  NIS  domain 
name  can  be  as  long  as  64  characters,  name  of  domain  may  exceed  the  maximum  file  name  length  allowed 
on  a  given  file  system.  If  that  length  is  exceeded,  the  subdirectory  name  becomes  a  truncated  version  of 
theNIS  domain  name. 

The  first  14  characters  of  all  NIS  domains  on  the  network  must  be  unique:  truncated  names  should  be 
checked  to  verify  that  they  meet  this  requirement. 

AUTHOR 

domainname  was  developed  by  Sun  Microsystems,  Inc. 
SEE  ALSO 

ypinit(lM),  getdomainname(2),  setdomainname(2). 
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NAME 

dos2ux,  ux2dos-  convert  ASCII  file  format 

SYNOPSIS 

dos2ux  file... 

ux2dos  file... 
DESCRIPTION 

dos2ux  and  ux2dos  read  each  specified  file  in  sequence  and  write  it  to  standard  output,  converting  to 
hp-ux  format  or  to  DOS  format,  respectively.  Each  file  can  be  either  DOS  format  or  hp-ux  format  for  either 
command. 

A  DOS  file  name  is  recognized  by  the  presence  of  an  embedded  colon  ( : )  delimiter;  see  dosif(4)  for  DOS  file 
naming  conventions. 

If  no  input  file  is  given  or  if  the  argument  -  is  encountered,  dos2ux  and  ux2dos  read  from  standard 
input.  Standard  input  can  be  combined  with  other  files. 

EXAMPLES 

Print  file  myf  ile  on  the  display: 

dos2ux  myfile 

Convert  f  ilel  and  f  ile2  to  DOS  format  then  concatenate  them  together,  placing  them  in  f  ile3. 
ux2dos  filel  file2  >  file3 

RETURN  VALUE 

dos2ux  and  ux2dos  return  0  if  successful  or  2  if  the  command  failed.  The  only  possible  failure  is  the 
inability  to  open  a  specified  file,  in  which  case  the  commands  print  a  warning. 

WARNINGS 

Command  formats  resembling: 

dos2ux  filel  file2  >  filel 

overwrite  the  data  in  filel  before  the  concatenation  begins,  causing  a  loss  of  the  contents  of  filel. 
Therefore,  be  careful  when  using  shell  special  characters. 

SEE  ALSO 

doschmod(l),  doscp(l),  dosdf(l),  dosls(l),  dosmkdir(l),  dosrm(l),  dosif(4). 
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NAME 

doschmod  -  change  attributes  of  a  DOS  file 

SYNOPSIS 

doschmod  [-u]  mode  device:  file  ... 

DESCRIPTION 

doschmod  is  the  DOS  counterpart  of  chmod  (see  chmod(l)). 

Options 

doschmod  recognizes  one  option: 

-u      Disable  argument  case  conversion.  I  n  the  absence  of  this  option,  all  DOS  file  names  are  con- 
verted to  uppercase. 

A  DOS  file  name  is  recognized  by  the  presence  of  an  embedded  colon  ( : )  delimiter;  see  dosif(4)  for  DOS  file 
naming  conventions. 

Metacharacters  *,?,  and  [  ...  ]  can  be  used  when  specifying  DOS  file  names.  These  must  be  quoted  when 
specifying  a  DOS  file  name,  because  file  name  expansion  must  be  performed  by  the  DOS  utilities,  not  by  the 
shell.  DOS  utilities  expand  filenames  as  described  in  regexp(5)  under  PATTERN  MATCHING  NOTATION. 

The  attributes  of  each  named  file  are  changed  according  to  mode,  which  is  an  octal  number  in  the  range  000 
to  0377.  mode  is  constructed  from  the  logical  OR  of  the  foil  owing  modes: 

200  Reserved.  Do  not  use. 
100         Reserved.  Do  not  use. 

040         Archive.  Set  whenever  the  file  has  been  written  to  and  closed. 
020         Directory.  Do  not  modify. 
010         Volume  Label.  Do  not  modify. 

004         System  file.  Marks  files  that  are  part  of  the  DOS  operating  system. 

002         Hidden  file.  Marks  files  that  do  not  appear  in  a  DOS  directory  listing  using  the  DOS  dir 
command. 

001         Read-Only  file.  Marks  files  as  read-only. 
WARNINGS 

Specifying  inappropriate  mode  values  can  make  files  and/or  directories  inaccessible,  and  in  certain  cases 
can  damage  the  file  system.  To  prevent  such  problems,  do  not  change  the  mode  of  directories  and  volume 
labels. 

Normal  users  should  have  no  need  to  use  mode  bits  other  than  001,  002,  and  040. 
EXAMPLES 

Mark  file  /dev/rfd9122  :memo  .  txt  as  a  hidden  file: 

doschmod  002  /dev/rf d9122 : memo . txt 
Mark  file  driveC  :  autoexec  .bat  read-only: 

doschmod  001  driveC : autoexec . bat 

SEE  ALSO 

chmod(l),  dos2ux(l),  doscp(l),  dosdf(l),  dosls(l),  dosmkdir(l),  dosrm(l),  chmod(2),  dosif(4). 
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NAME 

doscp  -  copy  to  or  from  DOS  files 

SYNOPSIS 

doscp  [-fvu]  filel  file2 

doscp  [-fvu]  filel  [file2  ...]  directory 
DESCRIPTION 

doscp  is  the  DOS  counterpart  of  cp  (see  cp(l)).  doscp  copies  a  DOS  file  to  a  DOS  or  hp-ux  file,  an  hp- 
ux  file  to  an  hp-ux  or  DOS  file,  or  hp-ux  or  DOS  files  to  an  hp-ux  or  DOS  directory.  The  last  name  in  the 
argument  list  isthe  destination  file  or  directory. 

A  DOS  file  name  is  recognized  by  the  presence  of  an  embedded  colon  ( : )  delimiter;  see  dosif(4)  for  DOS  file 
naming  conventions. 

Metacharacters  *,?,  and  [  ...  ]  can  be  used  when  specifying  both  hp-ux  and  DOS  file  names.  These  must 
be  quoted  when  specifying  a  DOS  file  name,  because  file  name  expansion  must  be  performed  by  the  DOS  util- 
ities, not  by  the  shell.  DOS  utilities  expand  file  names  as  described  in  regexp(5)  under  PATTERN  MATCH- 
ING  NOTATION. 

Thefile  name  -  (dash)  is  interpreted  to  mean  standard  input  or  standard  output  depending  upon  its  posi- 
tion in  the  argument  list. 

Options 

doscp  recognizes  the  following  options: 

-f      Unconditionally  writeover  an  existing  file.  I  n  the  absence  of  this  option,  doscp  asks  permis- 
sion to  overwrite  an  existing  hp-ux  file. 

-v      Verbose  mode,    doscp  prints  the  source  name. 

-u      Disable  argument  case  conversion.  I  n  the  absence  of  this  option,  all  DOS  file  names  are  con- 
verted to  upper  case. 

RETURN  VALUE 

doscp  returns  0  if  all  files  are  copied  successfully.  Otherwise,  it  prints  a  message  to  standard  error  and 
returns  with  a  non-zero  value. 

EXAMPLES 

Copy  the  files  in  the  hp-ux  directory  abc  to  the  DOS  volume  stored  as  hp-ux  filehard_disk: 

doscp  abc/*  hard_disk: 

Copy  DOS  file  /backup/log  through  the  HP-UX  special  file  /dev/rfd9127  to  HP-UX  file  logcopy 
located  in  the  current  directory: 

doscp  /dev/rfd9127 : /backup/log  logcopy 

Copy  DOS  file  zulu  on  the  volume  stored  asHP-ux  file  bb  to  standard  output: 
doscp  bb : zulu  - 

Copy  all  files  in  directory  /dameron  with  extension  txt  in  the  DOS  volume  /dev/rdsk/clt2d0  to 
the  hp-ux  directory  abacus  located  in  the  current  directory: 

doscp  ' /dev/rdsk/clt2d0 : /dameron/* .txt'  abacus 
WARNINGS 

doscp  works  more  reliably  if  you  use  a  raw  device  special  file  (/dev/rdsk/ )  than  a  block  device  special 
file. 

To  use  SCSI  floppy  disk  devices,  the  sf  lop  device  driver  must  be  configured  into  the  kernel.  (You  can  use 
the  ioscan  command  to  verify  the  configuration.) 

SEE  ALSO 

cp(l),  dos2ux(l),  doschmod(l),  dosdf(l),  dosls(l),  dosmkdir(l),  dosrm(l),  ioscan(llM)  dosif(4). 
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NAME 

dosdf  -  report  number  of  free  disk  clusters 

SYNOPSIS 

dosdf  devi  ce[ :  ] 

DESCRIPTION 

dosdf  is  the  DOS  counterpart  of  the  df  command  (see  df(l)).  It  prints  the  cluster  size  in  bytes  and  the 
number  of  free  clusters  on  the  specified  DOS  volume. 

SEE  ALSO 

df(l),  dos2ux(l),  doschmod(l),  doscp(l),  dosls(l),  dosmkdir(l),  dosrm(l),  dosif(4). 
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NAME 

dosls,  dosll  -  list  contents  of  DOS  directories 

SYNOPSIS 

dosls  [-aAudl]  device:  [file]  ... 

dosll  [-aAudl]  device:  [file]  ... 

DESCRIPTION 

dosls  is  the  DOS  counterpart  of  Is  (seels(l)). 

For  each  directory  named,  dosls  lists  the  contents  of  that  directory.  For  each  file  named,  dosls 
repeats  its  name  and  any  other  information  requested.  If  invoked  by  the  name  dosll,  the  -1  (ell)  option 
is  implied. 

Options 

dosls  and  dosll  recognizes  the  following  options: 

-a  List  all  directory  entries.  In  the  absence  of  this  option,  hidden  files,  system  files,  and  files 
whose  names  begin  with  a  dot  ( . )  are  not  listed. 

-A  Same  as  -a,  except  the  current  directory  and  the  parent  directory  are  not  listed.  For  the 
superuser,  this  option  defaults  to  being  set,  and  is  disabled  by  -A. 

-u  Disable  argument  case  conversion.  I  n  the  absence  of  this  option,  all  DOS  file  names  are  con- 
verted to  uppercase. 

-d  If  an  argument  is  a  directory,  list  only  its  name.  Often  used  with  -1  to  get  the  status  of  a 
directory. 

-1  List  in  long  format,  giving  file  attribute,  size  in  bytes,  and  the  date  and  time  of  last 
modification  for  each  file,  as  well  as  listing  the  DOS  volume  label.  Long  listing  is  disabled  if 
this  option  is  used  with  the  dosll  command. 

A  DOS  file  name  is  recognized  by  the  presence  of  an  embedded  colon  ( : )  delimiter;  see  dosif(4)  for  DOS  file 
naming  conventions. 

Metacharacters  *,?,  and  [  ...  ]  can  be  used  when  specifying  DOS  file  names.  These  must  be  quoted  when 
specifying  a  DOS  file  name,  because  file  name  expansion  must  be  performed  by  the  DOS  utilities,  not  by  the 
shell.  DOS  utilities  expand  filenames  as  described  in  regexp(5)  under  PATTERN  MATCHING  NOTATION. 

EXAMPLES 

These  examples  assume  that  a  DOS  directory  structure  exists  on  the  device  accessed  through  hp-ux  special 
file  /dev/rdsk/c2tld0. 

The  foil  owing  example  lists  all  of  the  files  in  the  root  directory  of  the  DOS  directory  structure: 

dosls  -a  /dev/rdsk/c2tld0 : 

The  following  example  lists  all  of  the  files  with  extension  bat  in  the  root  directory  of  the  DOS  directory 
structure: 

dosls  -a  ' /dev/rdsk/c2tld0 : * .bat' 

The  following  example  produces  a  long-format  listing  of  all  the  information  about  the  DOS  directory 
/dos/math,  but  does  not  list  the  files  in  the  directory: 

dosls  -Id  /dev/rdsk/c2tld0 : /dos/math 
SEE  ALSO 

dos2ux(l),  doschmod(l),  doscp(l),  dosdf(l),  dosmkdir(l),  dosrm(l),  ls(l),  dosif(4). 
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NAME 

dosmkdir  -  make  a  DOS  directory 

SYNOPSIS 

dosmkdir  [-u]  device:  directory  ... 

DESCRIPTION 

dosmkdir  is  the  DOS  counterpart  of  the  mkdir  command  (see  mkdir(l)).  It  creates  specified  directories. 
The  standard  entries,  .  for  the  directory  itself  and  .  .  for  its  parent,  are  made  automatically. 

There  is  one  option: 

-u      Disable  argument  case  conversion.  I  n  the  absence  of  this  option,  all  DOS  file  names  are  con- 
verted to  uppercase. 

A  DOS  file  name  is  recognized  by  the  presence  of  an  embedded  colon  ( : )  delimiter;  see  dosif(4)  for  DOS  file 
naming  conventions. 

DIAGNOSTICS 

dosmkdir  returns  0  if  all  directories  were  successfully  created.  Otherwise,  it  prints  a  message  to  stan- 
dard error  and  returns  non-zero. 

EXAMPLES 

Create  an  empty  subdirectory  named  numbers  under  the  directory  /math/lib  on  the  device  accessed 
through  HP-UX  special  file  /dev/rfd9122  : 

dosmkdir  /dev/rfd9122 : /math/lib/numbers 
SEE  ALSO 

dos2ux(l),  doschmod(l),  doscp(l),  dosdf(l),  dosls(l),  dosrm(l),  mkdir(l),  dosif(4). 
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NAME 

dosrm,  dosrmdir  -  remove  DOS  files  or  directories 

SYNOPSIS 

dosrm  [-friu]  device:file  ... 

dosrmdir  [-u]  device:file  ... 
DESCRIPTION 

dosrm  and  dosrmdir  are  DOS  counterparts  of  rm  and  rmdir  (see  rm(l)  and  rmdir(l),  respectively). 

dosrm  removes  the  entries  for  one  or  more  files  from  a  directory.  If  a  specified  file  is  a  directory,  an  error 
message  is  printed  unless  the  optional  argument  -r  is  specified  (see  below). 

dosrmdir  removes  entries  for  the  named  directories,  provided  they  are  empty. 
Options 

dosrm  and  dosrmdir  recognize  the  following  options: 

-f      (force)  Unconditionally  remove  the  specified  file,  even  if  the  file  is  marked  read-only. 

-r      Cause  dosrm  to  recursively  delete  the  entire  contents  of  a  directory,  followed  by  the  direc- 
tory itself,    dosrm  can  recursively  delete  up  to  17  levels  of  directories. 

-i      (interactive)  Cause  dosrm  to  ask  whether  or  not  to  delete  each  file.  If  -r  is  also  specified, 
dosrm  asks  whether  to  examine  each  directory  encountered. 

-u      Disable  argument  case  conversion.  I  n  the  absence  of  this  option,  all  DOS  file  names  are  con- 
verted to  uppercase. 

A  DOS  file  name  is  recognized  by  the  presence  of  an  embedded  colon  ( : )  delimiter;  see  dosif(4)  for  DOS  file 
naming  conventions. 

Metacharacters  *,?,  and  [  ...  ]  can  be  used  when  specifying  DOS  file  names.  These  must  be  quoted  when 
specifying  a  DOS  file  name,  because  file  name  expansion  must  be  performed  by  the  DOS  utilities,  not  by  the 
shell.  DOS  utilities  expand  filenames  as  described  in  regexp(5)  under  PATTERN  MATCHING  NOTATION. 

EXAMPLES 

These  examples  assume  that  a  DOS  directory  structure  exists  on  the  device  accessed  through  the  hp-ux 
special  file  /dev/rfd9122  . 

Recursively  comb  through  the  DOS  directory  /tmp  and  ask  if  each  DOS  file  should  be  removed  forcibly 
(that  is,  with  no  file  mode  checks): 

dosrm  -irf  /dev/rfd9122 : /tmp 

Remove  the  DOS  di  rectory  doug  from  the  DOS  volume  stored  asHP-ux  filehard_disk: 

dosrmdir  hard_disk : doug 

SEE  ALSO 

dos2ux(l),  doschmod(l),  doscp(l),  dosdf(l),  dosls(l),  dosmkdir(l),  rm(l),  rmdir(l),  dosif(4). 
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NAME 

du  -  summarize  disk  usage 

SYNOPSIS 

du  t-a|-s]  [-bkrx]  [-t  type]  [name  ...] 

DESCRIPTION 

The  du  command  gives  the  number  of  512-byte  blocks  allocated  for  all  files  and  (recursively)  directories 
within  each  directory  and  file  specified  by  the  name  operands.  The  block  count  includes  the  indirect  blocks 
of  the  file.  A  file  with  two  or  more  links  is  counted  only  once.  If  name  is  missing,  the  current  working 
directory  is  used. 

By  default,  du  generates  an  entry  only  for  the  name  operands  and  each  directory  contained  within  those 
hierarchies. 

Options 

Thedu  command  recognizes  the  following  options: 

-a  Print  entries  for  each  file  encountered  in  the  directory  hierarchies  in  addition  to  the 

normal  output. 

-b  For  each  name  operand  that  is  a  directory  for  which  file  system  swap  has  been 

enabled,  print  the  number  of  blocks  the  swap  system  is  currently  using. 

-k  Gives  the  block  count  in  102 4-byte blocks. 

-r  Print  messages  about  directories  that  cannot  be  read,  files  that  cannot  be  accessed, 

etc.  du  is  normally  silent  about  such  conditions. 

-s  Print  only  the  grand  total  of  disk  usage  for  each  of  the  specified  name  operands. 

-x  Restrict  reporting  to  only  those  files  that  have  the  same  device  as  the  file  specified  by 

the  name  operand.  Disk  usage  is  normally  reported  for  the  entire  directory  hierarchy 
below  each  of  the  given  name  operands. 

-t  type  Restrict  reporting  to  file  systems  of  the  specified  type.  (Example  values  for  type  are 
hfs,  cdfs,  nfs,  etc.)  Multiple -t  type  options  can  be  specified.  Disk  usage  is 
normally  reported  for  the  entire  directory  hierarchy  below  each  of  the  given  name 
operands. 

EXAMPLES 

Display  disk  usage  for  the  current  working  directory  and  all  directories  below  it,  generating  error  messages 
for  unreadabledirectories: 

du  -r 

Display  disk  usage  for  the  entire  filesystem  except  for  any  cdfs  or  nfs  mounted  file  systems: 
du  -t  hfs  / 

Display  disk  usage  for  files  on  the  root  volume  (/)  only.  No  usage  statistics  are  collected  for  any  other 
mounted  file  systems: 

du  -x  / 

WARNINGS 

Block  counts  are  incorrect  for  files  that  contain  holes. 

SEE  ALSO 

df(lM),  bdf(llM),  quot(lM). 

STANDARDS  CONFORMANCE 

du:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

echo  -  echo  (pri  nt)  arguments 

SYNOPSIS 

echo  [arg]  ... 

DESCRIPTION 

echo  writes  its  arguments  separated  by  blanks  and  terminated  by  a  new-line  on  the  standard  output.  It 
also  understands  C-l ike  escape  conventions;  beware  of  conflicts  with  the  shell's  use  of  \: 


\a 

write  an  alert  character 

\b 

backspace 

\c 

print  line  without  appendinga  new-line 

\f 

form-feed 

\n 

new-line 

\r 

carriage  return 

\t 

tab 

\v 

vertical  tab 

\\ 

backslash 

\n 

the  8-bit  character  whose  ASCII  code  is  the  1-,  2-,  3-  or  4-digit  octal  number  n,  whose  first 

character  must  be  a  zero. 

\0num 

write  an  8-bit  value  that  isthe  zero-,  one-,  two- or  three-digit  octal  number  num 

echo  is  useful  for  producing  diagnostics  in  command  files  and  for  sending  known  data  into  a  pipe. 
Notes 

Berkeley  echo  differs  from  this  implementation.  The  former  does  not  implement  the  backslash  escapes. 
However,  the  semantics  of  the  \c  escape  can  be  obtained  by  using  the  -n  option.  The  echo  command 
implemented  as  a  built-in  function  of  csh  follows  the  Berkeley  semantics  (see  csh(l)). 

EXTERNAL  INFLUENCES 
Envi  ronment  Variables 

LC_CTYPE  determines  the  interpretation  of  arg  as  singleand/or  multi-byte  characters. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used 
as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  echo  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

AUTHOR 

echo  was  developed  by  OSF  and  HP. 

SEE  ALSO 

sh(l). 

BUGS 

No  characters  are  printed  after  the  first  \c.  This  is  not  normally  a  problem. 

STANDARDS  CONFORMANCE 

echo:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

ed,  red  -  line-oriented  text  editor 

SYNOPSIS 

ed  [-p  string]  [-s|-]  [-x]  [file] 

red  [-p  string]  [-s|-]  [-x]  [file] 
DESCRIPTION 

Theed  command  executes  a  line-oriented  text  editor.  It  is  most  commonly  used  in  scripts  and  noninterac- 
tive  editing  applications  because,  even  though  it  can  be  used  interactively,  other  editors  such  as  vi  and  ex 
are  typically  easier  to  use  in  an  interactive  environment. 

If  file  is  specified,  ed  performs  an  e  command  (see  below)  on  the  named  file;  that  is  to  say,  the  file  is  read 
intoed's  buffer  so  that  it  can  be  edited. 

Options 

Thefollowing  options  are  recognized: 

-p  string    Use  string  as  the  prompt  string  when  in  command  mode.  By  default,  there  is  no  prompt 
string. 

-s  |-         Suppress  printing  of  byte  counts  by  e,  E,  r,  and  w  commands,  and  suppress  the  !  prompt 
after  a  !  command.  The- option  is  obsolescent  and  will  be  removed  in  a  future  release. 

-x  Perform  an  X  command  first  to  handlean  encrypted  file. 

File  Handling 

ed  operates  on  a  copy  of  the  file  it  is  editing;  changes  made  to  the  copy  have  no  effect  on  the  original  file 
until  a  w  (write)  command  is  given.  The  copy  of  the  text  being  edited  resides  in  a  temporary  file  called  the 
buffer.  There  is  only  one  buffer. 

red  is  a  restricted  version  of  ed  that  only  allows  editing  of  files  in  the  current  directory  and  prohibits  exe- 
cuting shell  commands  via  !  shell-command.  Attempts  to  bypass  these  restrictions  result  in  the  error  mes- 
sage restricted  shell. 

Both  ed  and  red  support  the  fspec(4)  formatting  capability.  After  including  a  format  specification  as  the 
first  line  of  file  and  invoking  ed  with  the  controlling  terminal  in  stty  -tabs  or  stty  tab3  mode  (see 
stty(l)),  the  specified  tab  stops  are  automatically  used  when  scanning  file.  For  example,  if  the  first  line  of  a 
file  contained 

<:t5,10,15  s72:> 

the  tab  stops  would  beset  at  columns  5,  10,  and  15,  and  a  maximum  line  length  of  72  would  be  imposed. 

Note  When  you  input  text,  ed  expands  tab  characters  as  they  are  typed  to  every  eighth  column  as  a 
default. 

Editor  Commands  Structure 

Commands  to  ed  have  a  simple  and  regular  structure:  zero,  one,  or  two  addresses  followed  by  a  single- 
character  command,  possibly  followed  by  parameters  to  that  command.  These  addresses  specify  one  or 
more  lines  in  the  buffer.  Every  command  that  requires  addresses  has  default  addresses,  so  that  the 
addresses  can  very  often  be  omitted. 

In  general,  only  one  command  is  allowed  on  a  line.  Append,  change,  and  insert  commands  accept  text 
input  which  is  then  placed  in  the  buffer  as  appropriate.  While  ed  is  accepting  text  following  an  append, 
change,  or  insert  command,  it  is  said  to  be  in  input  mode.  While  in  input  mode,  no  editor  commands  are 
recognized;  all  input  ismerely  collected.  To  terminate  input  mode,  typea  period  (.)  alone  at  the  beginning 
of  a  line. 

Regular  Expressions 

ed  supports  the  Basic  Regular  Expression  (RE)  syntax  (see  regexp(5)),  with  thefollowing  additions: 

•  The  null  RE  (for  example,  //)  is  equivalent  to  the  last  RE  encountered. 

•  If  the  closing  delimiter  of  an  RE  or  of  a  replacement  string  (for  example,  /)  would  be  the  last  char- 
acter before  a  newline,  that  delimiter  can  be  omitted,  in  which  case  the  addressed  line  is  printed. 
Thefollowing  pairs  of  commands  are  equivalent: 


HP-UX  Release  Hi:  December  2000 


-1- 


Section  1-195 


ed(l) 


ed(l) 


s/sl/s2  g/sl  ?sl 

s/sl/s2/p  g/sl/p  ?sl? 

Line  Addresses 

To  understand  line  addressing,  remember  that  ed  maintains  a  pointer  to  the  current  line.  Generally 
speaking,  the  current  line  is  the  last  line  affected  by  a  command.  The  exact  effect  of  a  given  command  on 
the  current  line  is  discussed  under  the  description  of  each  command.  Addresses  are  interpreted  according 
to  the  foil  owing  rules: 

1.  The  character  .  refers  to  the  current  line. 

2.  Thecharacter  $  refers  to  the  last  line  of  the  buffer. 

3.  A  decimal  number  n  refers  to  the  nth  line  of  the  buffer. 

4.  A  'x  refers  to  the  line  marked  with  the  mark  name  character  x,  which  must  be  a  lower-case 
letter.  Lines  are  marked  with  thek  command  described  below. 

5.  An  RE  enclosed  by  slashes  (/RE  /)  refers  to  the  first  line  found  by  searching  forward  from  the  line 
following  the  current  line  toward  the  end  of  the  buffer  and  stopping  at  the  first  line  containing  a 
stri ng  matchi ng  the  RE .  If  necessary,  the  search  wraps  around  to  the  begi nni ng  of  the  buffer  and 
continues  up  to  and  including  the  current  line,  so  that  the  entire  buffer  is  searched.  (Also  see 
WARNINGS  below.) 

6.  An  RE  enclosed  by  question  marks  (?RE  ?)  addresses  the  first  line  found  by  searching  backward 
from  the  line  preceding  the  current  line  toward  the  beginning  of  the  buffer  and  stopping  at  the 
first  line  containing  a  string  matching  the  RE.  If  necessary,  the  search  wraps  around  to  the  end 
of  the  buffer  and  continues  up  to  and  including  the  current  line.  (Also  see  WARN  I NGS  below.) 

7.  An  address  followed  by  a  plus  (+)  or  minus  (-)  sign  followed  by  a  decimal  number  specifies  that 
address  plus  or  minus  the  indicated  number  of  lines.  The  plus  sign  can  be  omitted. 

8.  If  an  address  begins  with  +  or  -,  the  addition  or  subtraction  is  calculated  with  respect  to  the 
current  line.  For  example,  -5  is  interpreted  as  .  -5. 

9.  If  an  address  ends  with  +  or  -,  1  is  added  to  or  subtracted  from  the  address,  respectively.  As  a 
consequence  of  this  and  rule  8  above,  the  address  -  refers  to  the  line  preceding  the  current  line. 
(To  maintain  compatibility  with  earlier  versions  of  the  editor,  the  circumflex  (")  and  -  characters 
are  interpreted  identically  when  encountered  in  addresses.)  Moreover,  multi pie trai li ng  +  and  - 
characters  have  a  cumulative  effect,  so  —  refers  to  the  second  line  preceding  the  current  line. 

10.  For  convenience,  a  comma  (, )  represents  the  address  pair  1,  $,  while  a  semicolon  (; )  represents 
the  pair  . ,  $. 

Commands  require  zero,  one,  or  two  addresses.  Commands  that  do  not  use  addresses  treat  the  presence  of 
an  address  as  an  error.  Commands  that  accept  one  or  two  addresses  assume  default  addresses  when  the 
number  of  addresses  specified  is  insufficient.  If  more  addresses  are  specified  than  a  given  command 
requires,  the  last  one  or  two  are  used  as  appropriate. 

Addresses  are  usually  separated  from  each  other  by  a  comma  (, ).  They  can  also  be  separated  by  a  semi- 
colon (; ),  in  which  case  the  current  line  ( . )  is  set  to  the  first  address,  after  which  the  second  address  is  cal- 
culated. This  feature  can  be  used  to  determine  the  starting  line  for  forward  and  backward  searches  (see 
rules  5  and  6  above).  The  second  address  of  any  two-address  sequence  must  correspond  to  a  line  in  the 
buffer  that  follows  the  line  corresponding  to  the  first  address. 

Editor  Commands 

I  n  the  following  list  of  ed  commands,  the  default  addresses  are  shown  in  parentheses  (parentheses  are  not 
part  of  the  address  and  should  not  be  placed  in  an  actual  command  except  for  other  purposes). 

It  is  generally  illegal  for  more  than  one  command  to  appear  on  a  line.  However,  any  command  (except  e, 
f ,  r,  or  w)  can  be  suffixed  by  1,  n,  or  p  in  which  case  the  current  line  is  respectively  either  listed,  num- 
bered, or  printed,  as  discussed  below  under  the  1,  n,  and  p  commands. 

(.  )a  The  a  (append)  command  reads  text  and  appends  it  after  the  addressed  line.  Upon  comple- 

text  tion,  the  new  current  line  is  the  last  inserted  line,  or,  if  no  text  was  added,  at  the  addressed 

line.  Address  0  is  legal  for  this  command,  causing  the  appended  text  to  be  placed  at  the 

begi  nni  ng  of  the  buffer. 
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( . ,  .  )c  The  c  (change)  command  deletes  the  addressed  lines  then  accepts  input  text  to  replace  the 

text  deleted  lines.  Upon  completion,  the  new  current  line  is  the  last  line  in  text  or,  if  no  text 

was  provided,  at  the  first  line  after  the  deleted  line  or  lines. 

( . ,  .  )d  The  d  (delete)  command  deletes  the  addressed  lines  from  the  buffer.  Upon  completion,  the 

new  current  line  is  the  first  line  following  the  deleted  text,  or  the  last  line  in  the  file  if  the 
deleted  line  or  lines  were  at  the  end  of  the  buffer. 

e  file  The  e  (edit)  command  deletes  the  entire  contents  of  the  buffer,  then  reads  in  the  named 

file.  Upon  completion,  the  new  current  line  is  the  last  line  in  the  buffer.  If  no  file  name  is 
given,  the  remembered  file  name,  if  any,  is  used  (see  the  f  command).  The  number  of 
characters  read  is  displayed,  and  file  is  remembered  for  possible  use  as  a  default  file  name 
in  subsequent  e,  r,  or  w  commands. 

If  the  file  name  starts  with  ! ,  the  rest  of  the  line  is  interpreted  as  a  shell  command  whose 
standard  output  is  to  be  read.  Such  a  shell  command  is  not  remembered  as  the  current  file 
name. 

Also  see  DIAGNOSTICS  below. 

E  file  The  E  (forced  edit)  command  is  identical  to  e  except  that  no  check  is  made  to  ensure  that 

the  current  buffer  has  not  been  altered  si  nee  the  last  w  command. 

f  file  If  file  is  specified,  the  f  (file  name)  command  changes  the  remembered  file  name  to  file. 

Otherwise,  it  prints  the  remembered  filename. 

(1,  $)g/ re /command-list 

Theg  (global)  command  first  marks  every  line  that  matches  the  given  RE.  Then,  for  every 
such  line,  the  given  command-list  is  executed  with  the  current  line  initially  set  to  that  line. 
A  single  command  or  the  first  of  a  list  of  commands  appears  on  the  same  line  as  the  global 
command.  All  lines  of  a  multiple-line  list  except  the  last  line  must  end  with  a  backslash 
(\).  a,  i,  and  c  commands  and  associated  input  are  permitted.  The  .  that  normally  ter- 
minates input  mode  can  be  omitted  if  it  would  be  the  last  line  of  the  command-list.  An 
empty  command-list  is  equivalent  to  the  p  command.  The  g,  G,  v,  and  V  commands  are 
not  permitted  in  the  command-list.  (Also  see  WARNINGS  below.) 

(1,$)G/RE/    The  interactive  G  (Global)  command  first  marks  every  line  that  matches  the  given  RE. 

Then,  for  every  such  line,  the  line  is  printed,  then  the  current  line  is  changed  to  that  line 
and  one  command  (other  than  a,  c,  i,  g,  G,  v,  or  V)  can  be  input  and  executed.  After  exe- 
cuting that  command,  the  next  marked  line  is  printed,  and  so  on.  A  newline character  acts 
as  a  null  command,  and  an  &  causes  the  re-execution  of  the  most  recent  command  executed 
within  the  current  invocation  of  G.  Note  that  the  commands  input  as  part  of  the  execution 
of  the  G  command  may  address  and  affect  any  lines  in  the  buffer.  The  G  command  can  be 
terminated  by  an  interrupt  signal  (ASCII  DEL  or  BREAK). 

The  h  (help)  command  gives  a  short  error  message  explaining  the  reason  for  the  most 
recent  ?  diagnostic. 

TheH  (Help)  command  causes  ed  to  enter  a  mode  in  which  error  messages  are  printed  for 
all  subsequent?  diagnostics.  It  also  explains  the  previous  ?  if  there  was  one.  TheHcom- 
mand  alternately  turns  this  mode  on  and  off.  I  nitially,  it  is  off. 

The  i  (insert)  command  inserts  the  given  text  before  the  addressed  line.  Upon  completion, 
the  current  line  is  the  last  inserted  line,  or,  if  there  were  none,  the  addressed  line.  This 
command  differs  from  the  a  command  only  in  the  placement  of  the  input  text.  Address  0  is 
not  legal  for  this  command. 

The  j  (join)  command  joins  contiguous  lines  by  removing  the  appropriate  newline  charac- 
ters. If  exactly  one  address  is  given,  this  command  does  nothing. 

Thek  (mark)  command  marks  the  addressed  line  with  the  namex,  which  must  bea  lower- 
case letter.  The  address  'x  then  addresses  this  line.  Upon  completion,  the  new  current 
line  remains  unchanged  from  before. 

The  1  (list)  command  writes  the  addressed  lines  to  standard  output  in  a  visually  unambigu- 
ous form.  Characters  listed  in  the  following  table  are  written  as  the  corresponding  escape 
sequence.  Nonprintable  characters  not  in  the  table  are  written  as  a  three-digit  octal 
number  (with  a  preceding  backslash  character)  for  each  byte  in  the  character  (most 
significant  byte  first). 


h 
H 

(.)i 
text 

(.,  .+l)j 
(.)kx 

(.,.)! 
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Long  lines  are  folded  with  the  point  of  folding  indicated  by  writing  a  backslash  character 
followed  by  a  newline.  The  end  of  each  line  is  marked  with  a  $.  An  1  (ell)  command  can  be 
appended  to  any  command  other  than  e,  E,  f ,  q,  Q,  r,  w,  or  ! .  The  current  line  number  is 
set  to  the  address  of  the  last  line  written. 


Escape 

ASCII 

Escape 

ASCII 

Sequence 

Represents 

Name 

Sequence 

Represents 

Name 

\\ 

backslash 

\ 

\r 

carriage  return 

CR 

\a 

alert 

BEL 

\t 

horizontal  tab 

HT 

\b 

backspace 

BS 

\v 

vertical  tab 

VT 

\f 

formfeed 

FF 

(. ,  .  )ma         The  m  (move)  command  repositions  the  addressed  lines  after  the  line  addressed  by  a. 

Address  0  is  legal  for  a,  causing  the  addressed  lines  to  be  moved  to  the  beginning  of  the  file. 
It  is  an  error  if  address  a  falls  within  the  range  of  moved  lines;  Upon  completion,  the  new 
current  line  is  the  last  line  moved. 

( . ,  .  )n  Then  (number)  command  prints  the  addressed  lines,  preceding  each  line  by  its  line  number 

and  a  tab  character.  Upon  completion,  the  new  current  line  is  the  last  line  printed.  Then 
command  can  be  appended  to  any  command  other  than  e,  f ,  r,  or  w. 

(.,  .  )p  The p  (print)  command  prints  the  addressed  lines.  Upon  completion,  the  new  current  line 

is  the  last  line  printed.  The  p  command  may  be  appended  to  any  other  command  other 
than  e,  E,  f ,  q,  Q,  r,  w,  or  ! .  For  example,  dp  deletes  the  current  line  and  prints  the  new 
current  line. 

P  TheP  (prompt)  command  causes  ed  to  prompt  with  an  asterisk  (*)  (or  with  string  if  the  -p 

option  was  specified  in  the  command  line)  for  all  subsequent  commands.  TheP  command 
alternately  turns  this  mode  on  and  off.  It  is  initially  on  if  the -p  option  was  specified;  oth- 
erwise, off.  Thecurrent  line  number  is  unchanged. 

q  The  q  (quit)  command  causes  ed  to  exit.  No  automatic  write  of  a  file  is  done  (but  see 

DIAGNOSTICS  below). 

Q  The  editor  exits  unconditionally  without  checking  for  changes  in  the  buffer  since  the  last  w 

command. 

($)r  file  The  r  (read)  command  reads  the  specified  file  into  the  buffer  after  the  addressed  line.  Ifno 
file  name  is  given,  the  remembered  file  name,  if  any,  is  used  (see  the  e  and  f  commands). 
The  remembered  file  name  is  not  changed  unless  file  is  the  very  first  file  name  mentioned 
since  ed  was  invoked.  Address  0  is  legal  for  r  and  places  the  contents  of  file  at  the  begin- 
ning of  the  buffer.  If  the  read  is  successful,  the  number  of  characters  read  is  displayed. 
Upon  completion,  the  new  current  line  is  the  last  line  read  into  the  buffer.  If  the  file  name 
starts  with  ! ,  the  rest  of  the  line  is  interpreted  as  a  shell  command  whose  standard  output 
is  to  be  read.  For  example,  $r  lis  appends  a  listing  of  files  in  the  current  directory  to 
the  end  of  the  file  being  edited.  A  shell  command  is  not  remembered  as  the  current  file 
name. 

(.,  .  )s/RE/replacement/flags 

The  s  (substitute)  command  searches  each  addressed  line  for  an  occurrence  of  the  specified 
RE.  In  each  line  in  which  a  match  is  found,  all  (nonoverlapped)  matched  strings  are 
replaced  by  replacement  if  the  global  replacement  indicator  g  appears  after  the  command. 
If  the  global  indicator  does  not  appear,  only  the  first  occurrence  of  the  matched  string  is 
replaced.  If  a  number  n  appears  after  the  command,  only  the  nth  occurrence  of  the 
matched  string  on  each  addressed  line  is  replaced.  It  is  an  error  for  the  substitution  to  fail 
on  all  addressed  lines.  Any  character  other  than  space  or  newline  can  be  used  instead  of  / 
to  delimit  the  RE  and  replacement.  Upon  completion,  the  new  current  line  is  the  last  line 
on  which  a  substitution  occurred.  (Also  see  WARNINGS  below.) 

If  an  ampersand  (&)  appears  in  replacement,  it  is  replaced  by  the  string  matching  the  RE 
on  the  current  line.  The  special  meaning  of  &  in  this  context  can  be  suppressed  by  preced- 
ing it  with  \. 

As  a  more  general  feature,  the  characters  \n,  where  n  is  a  digit,  are  replaced  by  the  text 
matched  by  the  nth  regular  subexpression  of  the  specified  RE  enclosed  between  \  (  and  \) . 
When  nested  parenthesized  subexpressions  are  present,  n  is  determined  by  counting 
occurrences  of  \  (,  startingfrom  the  left. 
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When  the  character  %  is  the  only  character  in  replacement,  the  replacement  used  in  the 
most  recent  substitute  command  is  used  as  the  replacement  in  the  current  substitute  com- 
mand. The  %  loses  its  special  meaning  when  it  is  in  a  replacement  string  containing  more 
than  one  character  or  when  preceded  by  a  \. 

A  line  can  be  split  by  substituting  a  newline  character  into  it.  Thenewlinein  replacement 
must  be  escaped  by  preceding  it  by  \.  Such  substitution  cannot  be  done  as  part  of  a  g  or  v 
command  list. 

The  value  of  flags  is  zero  or  more  of: 

n     Substitute  for  the  nth  occurrence  only  of  the  RE  found  on  each  addressed  line. 

g     Substitute  for  all  nonoverlapped  occurrences  of  the  RE  on  each  addressed  line. 

1     Write  to  standard  output  the  final  line  in  which  a  substitution  was  made.  The 
line  is  written  in  the  format  specified  for  the  1  command. 

n     Write  to  standard  output  the  final  line  in  which  a  substitution  was  made.  The 
line  is  written  in  the  format  specified  for  then  command. 

p     Write  to  standard  output  the  final  line  in  which  a  substitution  was  made.  The 
line  is  written  in  the  format  specified  for  thep  command. 

(. ,  .  )ta  Same  as  m  command,  except  that  a  copy  of  the  addressed  lines  is  placed  after  address  a 
(which  can  beO).  Upon  completion,  the  new  current  line  is  the  last  line  of  the  copy. 

u  Theu  (undo)  command  nullifies  the  effect  of  the  most  recent  command  that  modified  any- 

thing in  the  buffer,  that  is,  the  most  recent  a,  c,  d,  g,  G,  i,  j,  m,  r,  s,  t,  v,  or  V  com- 
mand. All  changes  made  to  the  buffer  by  a  g,  G,  v,  or  V  global  command  are  "undone"  as  a 
single  change;  if  no  changes  were  made  by  the  global  command  (such  as  with  g/RE/p), 
the  u  command  has  no  effect.  The  current  line  number  is  set  to  the  value  it  had  immedi- 
ately before  the  command  started. 

(1,  $)v/ re /command-list 

The  complement  of  the  global  command  g  in  that  the  lines  marked  during  the  first  step  are 
those  that  do  not  match  the  RE . 

(1,  $)V/RE/  The  complement  of  the  interactive  global  command  G  in  that  the  lines  marked  during  the 
first  step  are  those  that  do  not  match  the  RE . 

(l,$)w  file  The  w  (write)  command  writes  the  addressed  lines  into  the  named  file.  If  the  file  does  not 
exist,  it  is  created  with  mode  666  (readable  and  writable  by  everyone),  unless  the  current 
umask  setting  dictates  otherwise  (see  umask(l).  The  remembered  file  name  is  not 
changed  unless  file  is  the  very  first  file  name  encountered  since  ed  was  invoked.  If  no  file 
name  is  given,  the  remembered  file  name,  if  any,  is  used  (see  the  e  and  f  commands). 
Upon  completion,  the  current  line  address  is  unchanged.  If  the  command  is  successful,  the 
number  of  characters  written  is  displayed. 

If  the  file  name  starts  with  ! ,  the  rest  of  the  line  is  interpreted  as  a  shell  command  whose 
standard  input  is  the  addressed  lines.  Such  a  shell  command  is  not  remembered  as  the 
current  file  name. 

X  A  key  string  is  demanded  from  the  standard  input.  Subsequent  e,  r,  and  w  commands  will 

encrypt  and  decrypt  the  text  with  this  key,  using  the  algorithm  of  crypt(l).  An  explicitly 
empty  key  turns  off  encryption. 

($)=  The  line  number  of  the  addressed  line  is  displayed.  The  current  line  address  is  unchanged 

by  this  command. 

!  shell -command 

The  remainder  of  the  line  after  the  !  is  sent  to  the  shell  to  be  interpreted  and  executed  as  a 
command.  Within  the  text  of  that  command,  the  unescaped  character  %  is  replaced  with 
the  remembered  file  name.  If  a  !  appears  as  the  first  character  of  the  shell  command,  it  is 
replaced  with  the  text  of  the  previous  shell  command.  Thus,  !!  repeats  the  last  shell  com- 
mand. If  any  expansion  is  performed,  the  expanded  line  is  echoed.  Upon  completion,  the 
current  line  address  is  unchanged. 

(.+1)  newline  An  address  alone  on  a  line  causes  the  addressed  line  to  be  printed.  A  newline  alone  is 
equivalent  to  .  +lp.  This  technique  is  useful  for  stepping  forward  through  the  buffer. 
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If  an  interrupt  signal  (ASCI  I  DEL  or  BREAK)  is  sent,  ed  prints  a  ?  and  returns  to  its  command  level. 

The  following  size  limitations  apply:  256  characters  per  global  command  list,  64  characters  per  file  name, 
and  32  MB  characters  in  the  buffer.  The  limit  on  the  number  of  lines  depends  on  the  amount  of  user 
memory:  each  line  takes  1  word. 

EXTERNAL  INFLUENCES 
Environment  Variables 

SHELL  determines  the  preferred  command-line  interpreter  for  use  in  all  ! -style  commands.  If  this  vari- 
able  is  null  or  not  set,  thePOSIX  shell,  /usr/bin/sh,  isused  (see  sh-posix(l)). 

When  set,  TMPDIR  specifies  a  directory  to  be  used  for  temporary  files,  overriding  the  default  directory, 
/tmp. 

LANG  provides  a  default  value  for  internationalization  variables  that  are  unset  or  null.  If  LANG  is  unset  or 
null,  the  default  value  is  "C"  (see  lang(5)).  If  any  internationalization  variable  contains  an  invalid  setting, 
all  internationalization  variables  default  to  "C".  See  environ  (5). 

If  LC_ALL  is  set  to  a  nonempty  string  value,  it  overrides  the  values  of  all  the  other  internationalization 
variables,  includingLANG. 

LC_CTYPE  determines  the  interpretation  of  text  as  single-  and/or  multibyte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

DIAGNOSTICS 

?         Command  error.  Useh  or  H  to  get  a  detailed  explanation. 

?file     I  naccessiblefile.  Useh  or  H  to  get  a  detailed  explanation. 

If  changes  have  been  made  in  the  buffer  since  the  last  w  command  that  wrote  the  entire  buffer,  ed  warns 
you  if  you  attempt  to  destroy  the  buffer  with  an  e  or  q  command,  ed  displays  ?  or  warning :  expect- 
ing 'w' ,  then  continues  normal  editing  unless  you  enter  a  second  e  or  q  command,  in  which  case  the 
second  command  isexecuted.  The-s  or  -  command-line  option  inhibitsthisfeature. 

EXAMPLES 

Makea  simple  substitution  in  file-1  from  a  shell  script,  changing  the  first  occurrence  of  abc  in  any  line 
toxyz,  and  save  the  changes  in  f  ile-2 . 

cat  -  «  EOF   |  ed  -s  file-1 
1,$  s/abc/xyz/ 
w  file-2 

q 

EOF 

Note  that,  if  a  command  fails,  the  editor  exits  immediately. 
WARNINGS 

A  !  command  cannot  be  subject  to  a  g  or  a  v  command. 

The  !  command  and  the  !  escape  from  the  e,  r,  and  w  commands  cannot  be  used  if  the  the  editor  is 
invoked  from  a  restricted  shell  (seesh(l)). 

Thesequence  \n  in  a  regular  expression  does  not  match  a  newline character. 
Thel  command  does  not  handle  DEL  correctly. 

Files  encrypted  directly  with  the  crypt  command  with  the  null  key  cannot  be  edited  (see  crypt (1)). 

If  the  editor  input  is  coming  from  a  command  file  (e.g.,  ed  file  <  ed-cmd-file)  ,  the  editor  exits  at 
the  first  failure  of  a  command  in  the  command  file. 
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When  reading  a  file,  ed  discards  ASCI  I  NUL  characters  and  all  characters  after  the  last  newline.  This  can 
cause  unexpected  behavior  when  using  regular  expressions  to  search  for  character  sequences  containing 
NUL  characters  or  text  near  end-of-file. 

AUTHOR 

ed  was  developed  by  HP  and  OSF. 

FILES 

/tmp/ep       Temporary  buffer  file  where  p  is  the  process  number, 
ed.hup         Work  is  saved  here  if  the  terminal  ishungup. 

SEE  ALSO 

awk(l),  csh(l),  crypt(l),  ex(l),  grep(l),  ksh(l),  sed(l),  sh(l),  sh-bourne(l),  sh-posix(l),  stty(l),  vi(l),  fspec(4), 
environ(5),  lang(5),  regexp(5). 

Theed  section  in  Text  Processing:  User's  Guide. 

STANDARDS  CONFORMANCE 

ed:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 

red:  SVI D2,  SVI D3,  XPG2,  XPG3 
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NAME 

elfdump  -  dump  information  contained  in  object  files 
SYNOPSIS 

elfdump  [-acCfghH jkLopqrsStuUv]  [-D  num]  [+D  num2]  [-n  name]  [+s  section  ]  [-T 
num]  [+T  num2]  files... 

DESCRIPTION 

elfdump  takes  one  or  more  object  files  or  libraries  and  dumps  information  about  them.  The  following 
options  are  supported: 

-a  Dumps  archive  headers  from  an  archive  library, 

-c  Dumps  the  string  table(s). 

-C  (Modifier)  Demangles  C++ symbol  names  before  printing  them.  This  modifier  is  valid  with 

-c,  -r,  -s,  and  -t.  If  specified  with  -H,  this  modifier  is  ignored.  If  specified  with  -n 
name,  the  symbol  whose  unmangled  name  matches  name  will  be  printed,  and  its  symbol 
name  will  be  printed  as  a  demangled  name. 

-D  num  (Modifier)  Prints  the  section  whose  index  is  num. 

+D  num2  (Modifier)  Prints  the  sections  in  the  range  1  to  num2.  If  used  with  -D,  the  sections  in  the 
range  num  to  num2  are  printed.  Valid  with  -h,  -r,  -s.  If  used  with  -r,  only  the  reloca- 
tions which  apply  to  the  section(s)  in  the  range  are  printed. 

-f  Dumps  the  file  header. 

-g  Dumps  global  symbols  from  an  archive. 

-h  Dumps  the  section  headers. 

-H  (Modifier)  Dumps  output  information  in  hexadecimal,  octal,  or  decimal  format,  with  all 

options. 

-  j  Prints  the  object  dictionary  for  one  or  more  executable  files,  if  the  source  file  was  compiled 

with  +objdebug  or  linked  with +tools .  The  object  dictionary  entry  contains  the  name 
of  the  object  file  that  contributed  to  a  particular  section,  the  relative  offset  within  the  sec- 
tion, size  of  the  object  file's  contribution,  and  attributes  of  the  entry. 

-k  Prints  the  CTTI  section  headers  according  to  the  directory  member  relationship. 

-L  Dumps  the  .dynamic  section  in  shared  libraries  and  dynamically  linked  program  files. 

-n  name  (Modifier)  Dumps  information  about  the  specified  section  or  symbol  name.  This  option  is 
valid  with  -h,  -r,  -s,  and  -t.  If  used  with  -t,  name  pertains  to  a  symbol  name  and 
elfdump  will  only  dump  the  symbol  entry  whose  name  matches  name.  If  used  with  the 
other  options,  name  pertains  to  a  section  name  and  elfdump  will  only  dump  the  section 
whose  name  matches  it. 

-o  Dumps  the  optional  headers  (program  headers). 

-p  (Modifier)  Do  not  print  titles,  with  all  options. 

-q  (Modifier)  Suppresss  printing  CTTI  section  headers.  Valid  with  -k  option. 

-r  Dumps  the  relocations. 

-s  Dumps  the  section  contents. 

+s  name  (Modifier)  Dumps  the  section  specified  by  name.  Valid  with -c  and -t  only. 

-S  (Modifier)  Dumps  output  information  in  short  format.  Valid  with  the  -h  and  -o  options. 

-t  Dumps  the  symbol  tableentries. 

-T  num  Prints  the  symbol  whose  index  is  num. 

+T  num2  (Modifier)  Prints  the  symbols  in  the  range  0  to  num2.  If  used  with  — T,  print  the  symbols  in 
the  range  num  to  num2.  Valid  with -t. 

-u  Prints  the  usage  menu. 

-U  Prints  the  unwind  table. 
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-v 


(Modifier)  Verifies  the  CTTI  section  headers  before  printing.  Valid  with  the  -k  option. 


SEE  ALSO 
System  Tools 

ld(l) 


I  nvoke  the  link  editor 


Miscellaneous 

a. out (4) 
elf(3E) 


Assembler,  compiler,  and  linker  output 
Executableand  Linking  Format 


Texts  and  Tutorials: 

HP-UX  Linker  and  Libraries  Online  User  Guide 

(Seethe+help  option) 
HP-UX  Linker  and  Libraries  User's  Guide 

(See  manuals(5)  for  ordering  information) 
HP-UX  SoftwareTransition  Toolkit  (STK)  --  ELF  Object  Formats 

http : //www . software . hp . com/STK/ 
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NAME 

elm  -  process  electronic  mail  through  a  screen-oriented  interface 

SYNOPSIS 

elm  [-aKkmtVz]  [-f  folder] 

elm  [-s  subject]  address-list 
elm  -c  [alias-list] 
elm  -h 
elm  -v 

DESCRIPTION 

The  elm  program  is  a  screen-oriented  electronic  mail  processing  system.  It  supports  the  industry-wide 
MIME  standard  for  nontext  mail,  a  special  forms  message  and  forms  reply  mechanism,  and  an  easy-to-use 
alias  system  for  individualsand  groups,  elm  operates  in  three  principal  modes: 

•  I  nteractive  mode,  running  as  an  interactive  mail  interface  program.  (First  syntax.) 

•  Message  mode,  sendinga  single  interactive  message  to  a  list  of  mail  addresses  from  a  shell  command 
line.  (Second  syntax.) 

•  File  mode,  sending  a  file  or  command  output  to  a  list  of  mail  addresses  via  a  command-line  pipe  or 
redirection.  (Second  syntax.) 

In  all  three  cases,  elm  honors  the  values  that  are  set  in  your  elmrc  initialization  file,  in  your  elm  alias 
database,  and  in  the  system  elm  alias  database. 

The  modes  are  described  below  in  inverse  order  (shortest  description  to  longest). 
Options 

Thefollowing  options  are  recognized: 

-a  Set  arrow=ON.  Use  the  arrow  (->)  instead  of  the  inverse  bar  to  mark  the  current 

item  in  the  various  indexes.  This  overrides  the  setting  of  the  arrow  boolean  variable 
(seethe  ELM  CONFIGURATION  section). 

-c  Check  alias.  Check  the  aliases  in  alias-list  against  your  personal  elm  alias  database 

and  the  system  elm  alias  database.  The  results  are  written  to  standard  output. 
E  rrors  are  reported  first,  i  n  the  form: 

(alias  "alias"  is  unknown) 

Successes  are  reported  in  a  header-entry  format,  with  group  aliases  replaced  by  their 
members,  i  n  the  form: 

Expands  to:  alias-address  (fullname)  , 
alias-address  (fullname)  , 

alias-address  (fullname) 

If  there  is  no  full  name,  the"  (fullname) "  portion  isomitted. 

-f  folder  Folder  file.  Read  mail  from  the  folder  file  rather  than  from  the  incoming  mailbox.  A 
folder  file  is  in  the  standard  mail  file  format,  as  created  by  the  mail  system  or  saved 
by  elm  itself. 

-h  Help.  Display  an  annotated  list  of  command-lineoptions. 

-k  Set  sof tkeys=OFF  .  Disable  the  use  of  softkeys  (HP  2622  function  keys).  This 

overrides  the  setting  of  the  softkeys  boolean  variable  (see  the  ELM  CONFIGURA- 
TION section). 

-K  Set  keypad=OFF  and  softkeys=OFF  .  Disable  the  use  of  softkeys  and  arrow  cur- 

sor keys.  If  your  terminal  does  not  have  the  HP  2622  function  key  protocols,  this 
option  is  required.  This  overrides  the  settings  of  the  keypad  and  softkeys 
boolean  variables  (seethe  ELM  CONFIGURATION  section). 

-m  Set  menu=OFF.  Do  not  display  the  command  menus  on  several  Interactive  Mode 

screens.  This  overrides  the  setting  of  the  menu  boolean  variable  (see  the  ELM 
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CONFIGURATION  section). 

-s  subject      Subject.  Specify  the  subject  for  a  File  Mode  or  Message  Mode  message. 

-t  Set  usetite=OFF  .  Do  not  use  the  termcap  ti/te  and  terminf  o  cup  cursor  - 

positioning  entries.  This  overrides  the  setting  of  the  usetite  boolean  variable  (see 
the  ELM  CONFIGURATION  section). 

-V  Verbose  transmission.  Pass  outbound  messages  to  the  sendmail  mail  transport 

agent  using  the -v  option  (see  sendmail  (1M)). 

-v  Version.  Print  out  the  elm  version  information.  This  displays  the  revision  number 

and  build  date  as  well  as  the  compilation  features  that  were  specified  or  omitted. 

-z  Zero.  Do  not  enter  elm  if  there  is  no  mail  in  the  incoming  mailbox. 

Operands 

The  foil  owing  operands  are  recognized: 

address-list      A  blank-separated  list  of  one  or  more  mail  addresses,  your  elm  user  aliases,  or  elm 
system  aliases. 

alias-list         A  blank-separated  list  of  one  or  more  of  your  elm  user  aliases  or  elm  system  aliases. 

Terminology 

The  foil  owing  terms  are  used  throughout  this  manpage. 

blank 

A  space  or  a  tab  character,  sometimes  known  as  linear  white  space. 

body 

The  body  of  a  message.  See  message, 
boolean  variable 

See  configuration  variable. 

configuration  variable 

A  boolean,  numeric,  or  string  variablethat  defines  default  behavior  in  the  elm  mail  system.  See 
the  ELM  CONFIGURATION  section. 

elm  system  alias  text  file 

The  source  file,  /var /mail/  .  elm/aliases  .  text,  for  the  elm  system  alias  database, 
elm  user  alias  text  file 

The  source  file,  $HOME/  .  elm/aliases  .  text,  for  a  user's  own  elm  alias  database, 
elm  user  headers  file 

A  file,  $HOME/ .  elm/elmheaders,  where  a  user  can  specify  special  header  entries  that  are 
included  in  all  outbound  messages. 

elmrc  configuration  file 

A  file,  $HOME/  .  elm/elmrc,  that  defines  the  initial  values  for  elm  configuration  variables, 
envi  ronment  variable 

A  global  variableset  in  the  shell  that  called  elm.  Seethe  EXTERNAL  I NFLUENCES  section. 

folder 

A  file  that  contains  mail  messages  in  the  format  created  by  sendmail  or  elm. 
full  name 

The  first  and  last  name  of  a  user,  as  extracted  from  an  alias  text  file  or  from  the  /etc/passwd 
file. 

header 

The  header  of  a  message.  See  message. 
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header  entry 

An  entry  in  the  header  portion  of  a  message,  sometimes  called  a  header  field, 
incoming  mailbox 

The  mail  box  where  you  receive  your  mail,  usually /var/mail/ loginname. 
mail  directory 

The  di  rectory,  defined  by  the  maildir  string  variable,  wherea  user  normally  stores  mail  mes- 
sages in  folders. 

mail  transport  agent  (MTA) 

The  program  that  sends  and  receives  mail  messages  to  and  from  other  systems.  On  HP-UX  sys- 
tems, the  MTA  issendmail  (see  sendmail  (1M)). 

mailcap 

A  file  that  contains  information  on  how  to  compose  and  display  mail  messages  that  are  not  just 
seven-  and  eight-bit  ASCII  characters. 

metamail 

A  system  program  that  processes  nontext  mail  messages. 

message 

In  a  folder,  a  sequence  of  text  lines  comprised  of  a  message  delimiter,  a  header,  and  a  body.  The 
message  deli  miter  is  a  line  in  the  form: 

From  sender  date 

The  header  starts  after  the  message  delimiter  and  ends  with  the  first  null  line.  The  body 
begins  at  the  null  line  and  ends  at  the  next  message  delimiter.  A  body  can  have  subsections, 
called  attachments  or  body  parts,  which  have  are  comprised  of  a  boundary  delimiter,  a 
header,  and  a  body.  This  process  can  be  recursive.  See  the  METAMAIL  CONFIGURATION  sec- 
tion for  more  details. 

numeric  variable 

See  configuration  variable. 

sendmail  alias  database 

The  alias  database,  /etc/mail/aliases,  that  isused  by  the  sendmail  MTA  to  direct  local 
mail. 

signature  file 

A  file  that  is  appended  to  your  outbound  messages,  usually  containing  information  about  your- 
self. You  can  have  two  signature  files,  one  for  messages  to  your  local  machine  and  one  for  other 
messages.  Seethe  localsignature  and  remotesignature  string  variables. 

string  variable 

See  configuration  variable. 

user  name 

Usually  the  login  or  mailbox  name  of  someone  you  send  mail  to. 

variable 

See  configuration  variable  and  environment  variable. 

FILE  MODE 

If  standard  input  is  connected  to  a  pipe  or  to  a  file,  and  an  address-list  is  specified,  elm  operates  in  File 
Mode. 

The  output  of  the  previous  command  in  the  pipe,  or  the  content  of  the  file,  is  mailed  to  the  members  of  the 
address-list.  The  address-list  is  expanded,  based  on  your  elm  alias  database  and  the  system  elm  alias 
database,  and  placed  in  the  To :  header  entry. 

If  -s  is  omitted  or  subject  is  null,  subject  defaults  to: 
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no  subject    (file  transmission) 

Theexpressed  or  default  value  of  subject  is  placed  in  the  Subject :  header  entry. 
See  the  E XAM  P L  E  S  secti on . 

MESSAGE  MODE 

If  standard  input  is  connected  to  your  terminal,  and  an  address-list  is  specified,  elm  operates  in  Message 
Mode. 

The  address-list  is  expanded,  based  on  your  elm  alias  database  and  the  system  elm  alias  database,  and 
placed  in  the  To :  header  entry.  The  To:  header  entry  is  displayed,  in  the  same  form  as  for  the  Message 
Menu  m  (mail)  command  in  I  nteractive  Mode. 

The  value  of  subject,  if  nonnull,  or  a  null  string,  is  placed  in  the  Subject:  header  entry  and  the  Sub- 
ject: line  is  displayed  for  modification. 

If  askcc  is  ON  in  your  elmrc  file,  you  are  prompted  for  Copies  to : . 

Then  the  editor  defined  by  the  editor  string  variable  (if  a  signature  file  is  not  added)  or  the  alteditor 
string  variable(if  a  signaturefile  is  added)  isstarted  so  that  you  can  write  your  message. 

When  you  leave  your  editor,  you  enter  the  Send  Menu,  as  described  for  I  nteractive  Mode. 

If  you  choose  the  Send  Menu  s  (send)  command,  the  message  is  sent  and  the  program  terminates.  If  you 
select  the  Send  Menu  f  (forget)  command,  the  message  is  stored  in  $HOME/Canceled.mail  and  the 
program  terminates.  If  you  select  other  commands,  the  appropriate  action  occurs. 

See  the  E  XAM  P  L  E  S  secti  on . 
INTERACTIVE  MODE 

If  standard  input  is  connected  to  your  terminal,  and  there  is  no  address-list,  elm  operates  in  a  screen- 
oriented  I  nteractive  Mode. 

If  you  do  not  have  a  $HOME/.elm  directory,  or  if  you  do  not  have  a  mail  directory,  defined  bythemail- 
dir  string  variable,  you  are  asked  in  turn  if  they  should  be  created.  You  can  answer  y  for  yes,  n  for  no,  or 
q  for  quit.  For  y  or  n,  the  directories  are  created  or  not,  as  appropriate,  and  the  program  continues.  For 
q,  the  program  terminates. 

Overview 

When  invoked,  elm  reads  customized  variables  from  file  $HOME/ .  elm/elmrc  (if  it  exists)  to  initialize 
parameters.  This  file  can  be  saved  from  within  elm  and  some  of  these  variables  can  also  be  modified  with 
the  Message  Menu  o  (option)  command. 

elm  first  displays  the  Main  or  Message  Menu,  which  shows  index  entries  for  the  messages  in  your  incom- 
ing mailbox  or  selected  mail  folder.  Among  other  options,  you  can  read,  print,  reply  to,  and  forward  these 
messages,  as  well  as  initiate  new  mail  messages  to  other  users. 

You  can  also  move  to  the  Alias  Menu,  where  you  can  create,  modify,  and  delete  your  personal  aliases. 
From  the  Alias  Menu,  you  can  select  one  or  more  of  your  aliases  and  send  a  message  to  the  corresponding 
users. 

When  you  send  a  message,  you  can  include  attachments  in  a  number  of  formats,  such  as  PostScript, 
images,  audio,  and  video,  as  well  as  plain  text.  The  attachments  are  managed  separately,  which  can  be 
convenient  both  for  you  and  your  correspondents. 

Sending  Messages 

When  you  send  a  message,  you  use  the  editor  defined  by  the  editor  or  alteditor  string  variable.  If 
builtin  is  your  editor,  a  set  of  commands  described  in  the  Built-in  Editor  subsection  is  available  while 
composing  your  message 

If  the  elmheaders  file  exists  (see  the  HEADER  FILE  section),  all  nonblank  lines  in  the  file  are  copied  to 
the  headers  of  all  outbound  mail.  This  is  useful  for  adding  special  information  headers  such  as  X- 
Organization : ,  X-Phone :  ,  and  so  forth. 

MIME  Support 

elm  supports  the  MIME  protocols  for  headers  and  messages  (RFC  1521  and  RFC  1522)  enabling  it  to  view 
and  send  mail  containing  other  than  normal  ASCII  text.  For  example,  the  mail  contents  can  be  audio, 
video,  images,  etc.,  or  a  combination  of  these. 
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This  also  enables  conformance  with  SMTP  (RFC  821),  which  allows  only  7-bit  characters  in  the  message,  by 
using  Ml  ME-encoding  (base64  and  quoted-printable)  to  convert  8-bit  data  to  7-bit. 

elm  also  provides  a  facility  to  view  multipart  MIME  messages.  If  elm  receives  a  message  whose  type  is 
not  text/plain,  it  invokes  metamail,  which  invokes  the  appropriate  utility  (for  example,  ghost- 
view,  xv,  an  audio  editor,  mpeg)  to  display  the  different  mail  parts  according  to  the  content  type  (for 
example,  application/postscript,  image,  audio,  video). 

Aliases 

elm  has  its  own  alias  system  that  supports  both  personal  and  system-wide  aliases.  Personal  aliases  are 
specific  to  a  single  user;  system  aliases  are  availableto  everyone  on  the  system  where  the  system  aliases 
reside  (see  newalias(l)).  You  can  access  the  Alias  Menu  by  executing  the  Message  Menu  a  (alias)  com- 
mand. You  can  then  create  and  save  an  alias  for  the  current  message,  create  and  check  other  aliases,  and 
send  messages  to  one  or  more  aliases. 

Aliases  are  limited  to  2500  bytes.  If  you  wish  to  create  a  group  alias  that  is  longer  than  2500  bytes,  please 
ask  your  system  administrator  to  create  it  for  you  in  the  sendmail  system  alias  file, 
/etc/mail/aliases  (see sendmail (1M)). 

INTERACTIVE  MODE  MENUS  AND  COMMANDS 

This  section  begins  with  the  Message  Menu,  which  is  the  main  screen  for  I  nteractive  Mode.  The  rest  of  the 
menus  are  presented  alphabetically. 

Message  Menu 

The  Message  I  ndex  is  displayed  on  the  Message  Menu.  You  can  use  the  following  commands  to  manipulate 
and  send  messages.  Some  commands  use  a  series  of  prompts  to  complete  their  action.  You  can  useCtrl-D 
to  cancel  their  operations. 

The  commands  are: 

! command  Shell  Escape.  Send  command  to  the  shell  defined  by  the  shell  string  variable 
without  leaving  elm. 

#  Display  all  known  information  about  the  current  message. 

$  Resynchronizethe  messages  without  leaving  elm.  If  there  are  any  messages  marked 

for  deletion,  you  are  asked  if  you  want  to  delete  them.  If  any  messages  are  deleted  or 
any  status  flags  have  changed,  the  messages  are  written  back  to  the  mailbox  file.  All 
tags  are  removed. 

%  Display  the  computed  return  address  of  the  current  message. 

*  Set  the  current  message  pointer  to  the  last  message. 

+  Display  the  next  message  i  ndex  page,  when  applicable. 

Display  the  previous  message  index  page,  when  applicable. 

/pattern  Pattern  match.  Search  for  pattern  in  the  from  and  subject  fields  of  the  current  mes- 
sage index.  The  search  starts  at  the  current  message  and  wraps  around  to  the  begin- 
ning of  the  index.  The  current  message  pointer  is  set  to  the  first  message  that 
matches.  Uppercase  and  lowercase  are  treated  as  equivalent. 

//pattern  Pattern  match.  Search  for  pattern  through  all  the  lines  of  the  current  folder.  The 
search  starts  at  the  current  message  and  wraps  around  to  the  beginning  of  the  folder. 
The  current  message  pointer  is  set  to  the  first  message  that  matches.  Uppercase  and 
lowercase  are  treated  as  equivalent. 

<  Calendar.  Scan  message  for  calendar  entries  and  add  them  to  your  calendar  file.  A 

calendar  entry  isdefined  asa  line  whose  first  nonblank  characters  are ->,  asin: 

->calendar-entry 

The  delimiter  ->  and  surrounding  blanks  are  removed  before  the  entry  is  added  to 
the  calendar  file.  Resultant  blank  lines  are  ignored.  You  can  define  the  calendar  file 
name  in  your  elmrc  file  or  with  the  Options  Menu. 

=  Set  the  current  message  pointer  to  the  first  message. 

>  Save  in  folder.  Same  as  the  Message  Menu  s  (save)  command. 
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?key  ...  Helponkey.  Display  a  one-line  description  of  what  each  key  does.  ?  displays  a  sum- 

mary listing  for  each  command  available.  A  period  (.)  returns  you  to  the  Message 
Menu. 

@  Display  a  summary  of  the  messages  indexed  on  the  current  screen. 

|  Pipe  the  current  message  or  the  set  of  tagged  messages  through  other  filters  as 

desired.  Use  the  shell  defined  by  the  shell  string  variable. 

n  New  current  message.  Change  the  current  message  pointer  to  the  one  indexed  as  n. 

If  the  message  is  not  on  the  current  page  of  headers,  the  appropriate  page  displayed. 

Return  Read  current  message.  The  screen  is  cleared  and  the  current  message  is  displayed  by 

the  pager  defined  by  the  pager  string  variable. 

a  Alias.  Switch  totheAliasMenu. 

b  Bounce  mail.  This  is  similar  to  forwarding  a  message,  except  that  you  do  not  edit  the 

message  and  the  return  address  is  set  to  the  original  sender's  address,  rather  than  to 
your  address. 

c  Change  folder.  Thiscommand  is  used  to  change  the  file  whose  messages  are  displayed 

on  the  Message  Menu.  You  are  asked  for  a  file  name.  The  file  must  be  in  message 
format;  otherwise,  elm  aborts.  You  can  use  the  customary  wildcards  for  your  shell,  as 
well  as  the  foil  owing  special  names: 

!  Your  incoming  mail  folder. 

>  Your  received  folder,  defined  by  the  receivedmail  string  variable. 

<  Your  sent  folder,  defined  by  the  sentmail  string  variable. 

The  previously  used  folder. 

@alias  The  default  folder  for  the  login  name  associated  with  the  alias  alias. 

=filename       A  file  in  the  directory  defined  by  themaildir  string  variable. 

C  Copy  message.  Save  the  current  message  or  the  set  of  tagged  messages  to  a  folder. 

You  are  prompted  for  a  file  name  with  a  default  value.  The  default  value  is  a  file  in 
the  maildir  directory  with  the  user  name  of  the  sender  of  the  first  message  in  the 
set  being  saved.  Any  tags  are  cleared.  Unlike  the  >  and  s  commands,  the  messages 
are  not  marked  for  deletion  and  the  current  message  pointer  is  not  moved. 

d  Delete.  Mark  the  current  message  for  deletion.  See  also  Ctrl-D,  u,  and  Ctrl-U. 

Ctrl-D  Delete.  Mark  all  messages  for  deletion  that  contain  a  specified  pattern  in  the  From: 

and  Subject:  header  entries.  See  also  d,  u,  and  Ctrl-U. 

e  Edit.  Allows  you  to  physically  edit  the  current  mail  folder  using  the  editor  defined  by 

the  editor  string  variable.  When  you  exit  from  your  editor,  elm  resynchronizes 
your  mail  folder  (seethe  $  command). 

f  Forward  the  current  message.  You  are  asked  if  you  want  to  edit  the  outbound  mes- 

sage. If  you  answer  y,  the  characters  defined  by  the  prefix  string  variable  are 
prefixed  to  each  line  of  the  message  and  the  editor  defined  by  the  editor  string  vari- 
able will  be  invoked  to  allow  you  to  edit  the  message.  If  you  answer  n,  the  characters 
are  not  prefixed  and  the  editor  will  not  be  invoked.  I  n  either  case,  you  are  prompted 
for  To:  recipients,  allowed  to  edit  the  Subject:  header  entry,  and,  if  the  askcc 
boolean  variable  is  ON,  you  are  prompted  for  Cc:  recipients. 

If  the  userlevel  numeric  variable  is  1  (intermediate)  or  2  (expert),  and  there  was 
a  previous  sent  or  forgotten  message  in  this  session,  you  are  asked  if  you  would  I  ike  to 

Recall  last  kept  message  instead?  (y/n) 

If  you  answer  y,  the  previous  message  is  returned  to  the  send  buffer.  If  you  answer 
n,  the  current  message  is  copied  into  the  send  buffer  and  your  signature  file  (if  any)  is 
appended. 

Then  the  editor  is  invoked  if  you  chose  to  edit  the  outbound  message  (above).  When 
you  leave  the  editor,  or  if  it  was  not  invoked,  the  Send  Menu  is  displayed. 
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g  Group  reply.  The  reply  is  automatically  sent  To:  the  sender  of  the  message,  with 

Cc:  to  all  the  original  To :  andCc:  recipients.  Otherwise,  the  action  is  the  same  as 
for  the  r  command. 

h  Same  as  Return,  except  that  the  message  is  displayed  with  all  headers. 

j  Move  down.  Move  the  current  message  pointer  down  to  the  next  message. 

J  Move  down.  Move  the  current  message  pointer  down  to  the  next  undeleted  message. 

k  Moveup.  Move  the  current  message  pointer  up  to  the  previous  message. 

K  Moveup.  Move  the  current  message  pointer  up  to  the  previous  undeleted  message. 

1  (ell)  Limit  the  displayed  messages  to  those  that  contain  certain  string  values.  You  are 

prompted  with  Enter  criteria: .  To  set,  add  to,  or  clear  the  limiting  criteria, 
type  one  of: 

all  Clear  all  the  criteria  and  restore  the  normal  display, 

from  string  Restrict  to  entries  that  contain  string  in  the  From:  header, 

subject  string  Restrict  to  entries  that  contain  string  in  the  Subject :  header, 
to  string  Restrict  to  entries  that  contain  string  in  the  To :  header. 

You  can  add  limiting  criteria  by  repeating  the  1  command. 
Ctrl-L  Redraw  the  screen. 

m  Mail.  Send  mail  to  one  or  more  addresses.  You  are  prompted  for  To:  recipients,  a 

Subject:  and,  if  theaskcc  boolean  variable  is  ON,  Cc:  recipients. 

If  the  userlevel  numeric  variable  is  1  (intermediate)  or  2  (expert),  and  there  was 
a  previous  sent  or  forgotten  message  in  this  session,  you  are  asked  if  you  would  I  ike  to 

Recall  last  kept  message  instead?  (y/n) 

If  you  answer  y,  the  previous  message  is  returned  to  the  send  buffer.  If  you  answer 
n,  the  signaturefile  (if  any)  is  copied  into  the  send  buffer. 

Then,  the  editor  defined  by  the  editor  string  variable  is  invoked.  After  you  exit 
from  your  editor,  the  Send  Menu  is  displayed. 

n  Next  message.  Advances  the  current  message  pointer  to  the  next  message,  and 

displays  that  message  as  for  the  Return  command. 

o  Options.  Invokes  the  Options  Menu,  permitting  you  to  change  certain  configuration 

options.  The  changeable  options  are  defined  by  the  conf  igoptions  string  vari- 
able. 

p  Print.  Print  the  current  message  or  the  set  of  tagged  messages  using  the  command 

defined  by  the  print  string  variable.  The  current  message  pointer  does  not  move. 
Tagged  messages  remain  tagged. 

q  Quit.  Gracefully  terminate,  performing  message  cleanup  according  to  defined  per- 

sonal preferences.  You  can  choose  to  actually  delete  messages  marked  for  deletion. 
For  your  incoming  mailbox,  you  can  choose  to  keep  undeleted  mail  in  the  mailbox  or 
move  it  to  the  received  folder  defined  by  the  receivedmail  string  variable. 

If  the  ask  boolean  variable  is  ON,  you  may  be  asked  the  following  questions.  The 
actions  described  are  all  performed  after  you  have  answered  all  the  relevant  ques- 
tions. 

Delete  messages?  (y/n) 

This  question  is  asked  if  you  have  messages  marked  for  deletion.  The  default 
answer  is  provided  by  the  alwaysdelete  boolean  variable  (ON  means  y  (yes) 
and  OFF  means  n  (no)). 

If  you  answer  y,  all  messages  marked  for  deletion  will  be  deleted. 

If  you  answer  n,  all  messages  marked  for  deletion  will  be  restored  to  their 
former  read,  unread,  or  new  state. 
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Move  read  messages  to  "received"   folder?  (y/n) 

This  question  is  asked  if  you  are  reading  your  incoming  mailbox  and  if  you  have 
messages  that  have  been  read.  The  default  answer  is  provided  by  the  always- 
store  boolean  variable  (ON  means  y  (yes)  and  OFF  means  n  (no)). 

If  you  answer  y,  undeleted  messages  that  have  been  read  will  be  moved  to  the 
folder  defined  by  the  receivedmail  string  variableand  the  next  question  will 
also  be  asked. 

If  you  answer  n,  all  undeleted  messages  are  returned  to  your  incoming  mailbox 
and  the  next  question  is  not  asked. 

Keep  unread  messages  in  incoming  mailbox?  (y/n) 

This  question  is  asked  if  you  are  reading  your  incoming  mailbox,  if  you  answered 
y  to  the  Move  read  messages...  question  (or  it  was  not  asked),  and  if  you 
have  messages  that  have  not  been  read.  The  default  answer  is  provided  by  the 
alwayskeep  boolean  variable  (ON  means  y  (yes)  and  OFF  means  n  (no)). 

If  you  answer  y,  all  undeleted  unread  (new  and  old)  messages  are  returned  to 
your  incoming  mailbox. 

If  you  answer  n,  all  undeleted  unread  messages  will  be  moved  to  the  folder 
defined  by  the  receivedmail  string  variable. 

If  the  ask  boolean  variable  is  OFF,  the  answers  to  the  questions  (which  are  not 
displayed)  are  taken  automatically  from  the  values  of  the  alwaysdelete ,  always - 
store,  and  alwayskeep  boolean  variables,  respectively. 

Q  Quick  quit.  This  is  equivalent  to  executing  the  q  command  with  the  ask  boolean 

variable  set  to  OFF. 

r  Reply  to  the  sender  of  the  current  message.  If  the  autocopy  boolean  variable  is 

OFF,  you  are  asked  if  the  source  message  should  be  copied  into  the  edit  buffer.  If  it  is 
ON,  the  message  is  copied  automatically.  If  copied  in,  all  lines  from  the  message  are 
preceded  by  the  prefix  string  defined  by  the  prefix  string  variable.  The  To: 
header  i  s  set  to  the  sender  of  the  message  (or  the  address  i  n  the  Reply-To :  header, 
if  one  was  set),  the  Subject :  is  set  to  the  subject  of  the  message,  preceded  by  Re : , 
and  presented  for  you  to  edit.  If  the  askcc  boolean  variable  is  ON,  you  are  prompted 
for  Cc:  recipients.  Then,  the  editor  defined  by  the  editor  string  variable  is 
invoked.  After  you  exit  from  your  editor,  the  Send  Menu  is  displayed. 

s  Save  i  n  folder  (same  as  >).  Save  the  current  message  or  the  set  of  tagged  messages  to 

a  folder.  You  are  prompted  for  a  file  name  with  a  default  value.  The  default  value  is  a 
file  in  the  maildir  directory  with  the  login  name  of  the  sender  of  the  first  message 
in  the  set  being  saved.  Any  tags  are  cleared  and  the  messages  are  marked  for  dele- 
tion. The  current  message  pointer  is  moved  to  the  first  undeleted  message  after  the 
I  ast  saved  message. 

t  Tag  toggle.  Tag  the  current  message  for  a  later  operation  and  move  the  current  mes- 

sage pointer  to  the  next  undeleted  message.  The  operation  can  be  one  of  | ,  C,  p,  and 
s. 

Or,  remove  the  tag  from  a  tagged  message.  See  also  the  Ctrl-T  command. 

T  Tag  toggle.  Tag  the  current  message  for  a  later  operation  and  remain  at  the  current 

message.  The  operation  can  be  one  of  | ,  C,  p,  and  s. 

Or,  remove  the  tag  from  a  tagged  message.  See  also  the  Ctrl-T  command. 

Ctrl-T  Tag  all  messages  containing  the  specified  pattern.  Or  remove  the  tags  from  all  tagged 

messages. 

If  any  messages  are  currently  tagged,  you  are  asked  if  the  tags  should  be  removed. 
Answer  y  to  remove  the  old  tags;  answer  n  to  keep  them.  In  either  case,  you  are 
prompted  for  a  string  to  match  in  either  the  From:  or  Subject :  line  of  each  mes- 
sage. All  messages  that  match  the  criterion  are  tagged.  If  you  enter  a  null  string 
(carriage-return  alone),  no  more  messages  are  tagged. 
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u  Undelete.  Remove  the  deletion  mark  from  the  current  message.  See  also  d,  Ctrl-D, 

and  Ctrl-U. 

Ctrl-U  Undelete.  Remove  any  deletion  mark  from  all  messages  that  contain  a  specified  pat- 

tern i  n  the  From :  and  Subject:  header  entries.  See  also  d,  Ctrl-D,  and  u. 

v  View  attachments.  I  nvoke  the  Attachment  View  Menu  for  the  current  message. 

x  Exit.  Exit  without  changing  the  mailbox.  If  changes  are  pending,  such  as  deletions, 

you  are  asked  if  they  can  be  abandoned.  If  you  answer  y,  the  changes  are  abandoned 
and  the  program  terminates.  If  you  answer  n  the  exit  is  abandoned  and  you  return  to 
the  Message  Menu  command  prompt. 

X  Exit  immediately  without  changingthe  mailbox.  All  pending  changes  are  abandoned. 

Message  Index 

The  messages  in  the  current  folder  are  indexed  on  the  Message  Menu,  one  per  line,  in  the  format: 

sssnum  mmm  d  from  (lines)  subject 
defined  as: 

sss         A  three-character  status  field,  described  in  the  Message  Status  subsection, 
num        The  ordinal  message  index  number. 

mmm      The  month  from  the  last  Date :  header  entry,  or  from  the  From  message  header. 

d  The  day  from  the  last  Date:  header  entry,  or  from  the  From  message  header. 

from        Either  the  sender  name  from  the  last  From:  header  entry  or  from  the  From  message 
header. 

lines       The  number  of  lines  in  the  message. 

subject     The  subject  description  from  the  first  Subject:  header  entry,  truncated  to  fit  your 
screen. 

The  current  message  index  entry  is  either  highlighted  in  inverse  video  or  marked  in  the  left  margin  with  an 
arrow  (->).  See  the  -a  option  in  the  Options  subsection  and  the  arrow  string  variable  in  the  ELM  CON- 
FIGURATION section. 

Message  Status 

The  first  three  characters  of  each  message  index  entry  describe  the  message  status.  Each  can  be  blank  or 
one  of  the  val  ues  descri  bed  bel  ow  i  n  descendi  ng  order  of  precedence. 

When  a  message  has  more  than  one  status  flag  of  a  particular  type  set,  the  highest-precedence  indicator  is 
displayed  on  the  index  line.  For  example,  if  a  forms  message  (F)  is  also  marked  as  company  confidential 
(C),  thee  rather  than  theF  status  character  is  displayed. 

Column  One:  Variable  Status 

D     Deleted.  The  message  is  marked  for  deletion. 

E     Expired.  The  date  specified  in  the  Expires :  header  entry  is  older  than  today,  elm  accepts 
the  fol  I  owi  ng  date  formats: 

Mon,    11  Jun  90        (format  produced  by  elm  in  the  Header  Menu) 
Jun  11,  90 
11  Jun,  90 

9006111324GMT  (I SO  X. 400 format:  YYMMDDhhmmzzz) 

N     New.  The  message  was  received  after  your  last  elm  session  or  during  the  current  session.  The 
message  has  not  been  read. 

O     Old.  Themessagewas  received  beforeor  duringyour  last  elm  session.  It  was  marked  N  in  your 
last  session  and  it  was  not  read. 

Blank.  The  message  has  been  read. 
Column  Two:  Permanent  Status 
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C  Confidential.  The  Sensitivity:  3  header  entry  is  present.  The  message  is  considered  com- 
pany confidential,  as  specified  by  the  ISO  X.400  standard.  You  can  set  this  value  for  outbound 
mail  with  the  user-defined  option  of  the  Header  Menu. 

U     Urgent.  The  message  contains  a  Priority :  header  entry. 

P  Private.  The  Sensitivity :  2  header  entry  is  present.  The  message  is  considered  private, 
as  specified  by  the  ISO  X.400  standard.  You  can  set  this  value  for  outbound  mail  with  the  user- 
defined  option  of  the  Header  Menu. 

A     Action.  The  message  contains  an  Action:  header  entry. 

F  Forms.  The  message  is  an  elm  forms  message.  The  message  contains  a  Content- 
Type:  mailform  header  entry. 

M  MIME.  The  message  or  its  attachments  is  in  a  MIME  format  that  can  be  displayed  using 
metamail . 

?     MIME.  The  message  or  its  attachments  is  in  a  MIME  format  whose  version  isnot  supported. 
Blank.  Normal  status. 

Column  Three:  Tagged  Status 

+  Tagged.  Tagged  messages  are  handled  as  a  group  by  some  commands.  See  t  and  other  com- 
mands in  the  Message  Menu  subsection. 

Blank.  The  message  is  not  tagged. 
Built-in  Editor 

When  you  are  composing  an  outbound  message  with  thebuiltin  built-in  editor,  it  prompts  you  for  text 
lines  with  an  empty  line.  Enter  a  period  ( . )  to  end  the  message  and  continue  with  the  Send  Menu. 

Built-in  editor  commands  are  lines  that  begin  with  an  escape  character,  defined  by  the  escape  string  vari- 
able. The  default  escape  character  is  tilde  (~). 

Note:  Some  remote  login  programs  use  tilde  as  their  default  escape  character  when  it  is  the  first  character 
on  a  line.  (You  can  tell,  because  the  tilde  does  not  print.)  Usually,  the  tilde  is  transmitted  when  you  enter 
a  second  character  that  is  not  recognized  by  the  program  or  when  you  enter  a  second  tilde.  See  the  pro- 
gram documentation  for  further  information. 

The  built-in  editor  commands  are: 

~ !  [command]        Execute  the  shell  command,  if  one  is  given  (as  in  ~  !  Is),  or  start  an  interactive 
shell,  usingthe  shell  defined  by  the  shell  string  variable. 

~<  command  Execute  the  shell  command  and  pi  ace  the  output  of  the  command  into  the  editor 

buffer.  For  example,  "~<  who"  inserts  the  output  of  the  who  command  in  your 
message. 

~?  Print  a  brief  help  menu. 

Start  a  line  with  a  singletilde  (~)  character. 
~b  Prompt  for  changes  to  the  Blind-Carbon-Copy  (Bcc:  (list. 

~c  Prompt  for  changes  to  the  Carbon-Copy  (Cc: )  list. 

~e  I  nvoke  the  editor  defined  for  the  easyeditor  string  variable  on  the  message, 

if  possible. 

~f  [options]  Add  the  specified  list  of  messages  or  the  current  message.  This  uses  readmail 

which  means  that  all  readmail  options  are  available(see  readmail  (1)). 

~h  Prompt  for  changes  to  all  the  available  headers  (To: ,  Cc: ,  Bcc: ,  and  Sub- 

ject : ). 

~m  [options]  Same  as  ~f,  but  each  line  is  prefixed  with  the  current  prefix.  Seetheprefix 

string  variable. 

~o  Prompt  for  the  name  of  an  editor  to  use  on  the  message. 

~p  Print  out  the  message  as  typed  in  so  far. 
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~r  filename  I  nclude  (read  in)  the  contents  of  the  specified  file. 

~s  Prompt  for  changes  to  the  Subject :  line. 

~t  Prompt  for  changes  to  the  To:  list. 

~v  Invoke  the  editor  defined  for  the  visualeditor  string  variable  on  the  mes- 


sage, if  possible. 
Alias  Menu 

TheAlias  Menu  isinvoked  with  the  Message  Menu  a  command.  Thesourcetext  for  your  alias  file  is  stored 
in  the  file  $HOME/  .  elm/ aliases  .  text.  You  can  edit  this  file  directly  or  with  the  following  com- 
mands. 

The  aliases  currently  compiled  into  your  database  and  the  system  database  are  displayed  in  an  indexed  list 
similar  to  the  Message  Menu.  The  entry  format  is  described  in  the  Alias  Index  subsection.  The  index  is 
sorted  in  the  order  defined  by  the  aliassortby  string  variable. 

The  commands  are: 

$  Resynchronize  your  alias  text  file  and  your  alias  database  by  rebuilding  the  database 

from  the  text  file  by  running  newalias .  Aliases  marked  for  deletion  are  removed, 
tagged  aliases  are  untagged,  and  new  and  changed  aliases  are  recognized.  The  alias 
screen  is  updated  to  reflect  these  changes. 

+  Display  the  next  alias  index  page,  when  applicable. 

Displaythepreviousaliasindexpage,  when  applicable. 

/pattern         Pattern  match.  Search  for  pattern  in  the  alias  and  user  name  fields  of  the  alias  list. 

The  search  starts  at  the  current  alias  and  wraps  around  to  the  beginning  of  the  alias 
list.  The  current  alias  pointer  is  set  to  the  first  alias  that  matches.  Uppercase  and 
lowercase  are  treated  as  equivalent. 

//pattern  Pattern  match.  Search  for  pattern  through  all  the  fields  of  the  alias  list  (alias,  user 
name,  comment,  and  address).  The  search  starts  at  the  current  alias  and  wraps 
around  to  the  beginning  of  the  alias  list.  The  current  alias  pointer  is  set  to  the  first 
alias  that  matches.  Uppercaseand  lowercase  are  treated  as  equivalent,  /pattern  Pat- 
tern match.  This  command  allows  you  to  search  through  all  the  alias  and  username 
entries  in  the  alias  list,  starting  at  the  current  alias  and  continuing  through  the  end. 
If  the  first  character  of  the  pattern  is  a  /,  then  the  comment  and  the  fully  expanded 
address  fields  are  also  included  in  the  search.  The  search  is  case-insensitive.  This 
allows  you  to  find  a  specific  alias  in  a  situation  where  there  are  a  large  number  of 
aliases. 

Help  on  key.  Display  a  one-line  description  of  what  each  key  does.  ?  displays  a  sum- 
mary listing  for  each  command  available.  A  period  (. )  returns  you  totheAliasMenu. 

Alias  current  message.  This  allows  you  to  create  an  alias  that  has  the  return  address 
of  the  current  message  as  the  address  field  of  the  alias.  It  prompts  for  a  uniquealias 
name  and  allows  you  to  edit  the  comment  and  address  fields. 

Change  the  current  user  alias.  The  old  values  of  the  alias  fields  are  used  as  the 
defaults  in  the  prompts  for  the  new  values.  You  cannot  change  the  alias  name.  If  the 
alias  name  is  one  of  a  multiple-alias  record,  it  is  removed  from  that  record  and  stored 
as  a  separate  record.  The  old  alias  is  marked  N.  Changes  are  effective  after  the  next 
alias  resynchronization. 

Mark  the  current  user  alias  for  deletion.  The  deletions  are  made  when  you  exit  from 
the  Alias  Menu  with  an  q,  r,  or  i  command  or  you  resynchronize  your  alias  database 
with  the  $  command.  (You  cannot  delete  a  system  alias  in  this  way.) 

Delete  user  aliases  with  a  specified  search  pattern. 

Edit  your  aliases. text  file,  using  the  editor  defined  in  the  editor  string  vari- 
able. Your  aliases  are  resynchronized  when  you  finish  editing  (seethe  $  command). 

Display  a  fully  expanded  alias.  The  currently  selected  alias  is  fully  expanded  and 
displayed. 


?key  ... 
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c 
d 

Ctrl-D 

e 

f 


Section  1-214 


-11- 


HP-UX  Release  Hi:  December  2000 


elm(l) 


elm(l) 


i,l  See  the  Alias  Menu  q  and  Q  commands. 

j  Move  down.  Move  the  current  alias  pointer  down  to  the  next  alias. 

J  Movedown.  Move  the  current  alias  pointer  down  to  the  next  undeleted  alias. 

k  Move  up.  Move  the  current  alias  pointer  up  to  the  previous  alias. 

K  Move  up.  Move  the  current  alias  pointer  up  to  the  previous  undeleted  alias. 

1  (ell)  Limit  the  displayed  aliases  to  certain  types  or  those  that  contain  certain  string  values. 

You  are  prompted  with  Enter  criteria:  .  To  set,  add  to,  or  clear  the  limiting  cri- 
teria, type  one  of: 

all  Clear  all  the  criteria  and  restore  the  normal  display. 

alias  string         Restrict  to  alias  names  containing  string. 

name  string  Restrict  to  full  names  (first  name  and  last  name)  containing 

string. 

group  Restrict  to  group  aliases  (can  include  system  and  user  aliases), 

person  Restrict  to  person  aliases  (can  include  system  and  user  aliases), 

system  Restrict  to  system  aliases  (can  include  group  and  person  aliases), 

user  Restrict  to  system  aliases  (can  include  group  and  person  aliases). 

You  can  add  limiting  criteria  by  repeating  the  1  command. 
Ctrl-L  Redraw  the  screen. 

m  Mail  to  the  current  alias  or  to  the  set  of  tagged  aliases.  The  corresponding  expanded 

addresses  are  placed  in  the  To:  header  entry,  and  processing  continues  as  for  the 
Message  Menu  m  (mail)  command.  Thetags  are  cleared. 

n  Make  a  user  alias,  elm  prompts  for  a  unique  alias  name,  then  for  an  address.  The 

information  provided  is  added  to  your  individual  aliastext  file 
($HOME/  .  elm/aliases  .  text),  then  added  to  the  database. 

q  Exit.  Return  to  the  Message  Menu.  If  aliases  are  marked  for  deletion,  you  are  asked 

if  you  want  to  delete  them.  The  alias  index  pointer  is  retained.  If  the  alias  text  file 
was  changed,  the  database  is  resynchronized. 

Q  Exit.  Return  to  the  Message  Menu.  If  aliases  are  marked  for  deletion,  the  mark  is 

retained  and  the  alias  is  not  deleted.  The  alias  index  pointer  is  retained.  If  the  alias 
text  file  was  changed,  the  database  is  resynchronized. 

r,R  See  the  Alias  Menu  q  and  Q  commands. 

t  Tag  the  current  alias  for  a  later  operation  and  move  the  current  alias  pointer  to  the 

next  undeleted  alias.  The  operation  can  be  one  of  c,  m,  or  n. 

Or,  remove  the  tag  from  a  tagged  alias.  See  also  the  Ctrl-T  command. 

T  Tag.  Tag  the  current  alias  for  a  later  operation  and  remain  at  the  current  alias.  The 

operation  can  be  one  of  c,  m,  or  n. 

Or,  remove  the  tag  from  a  tagged  alias.  See  also  the  Ctrl-T  command. 

Ctrl-T  Tag  all  aliases  containing  a  specified  pattern  for  a  later  operation.  The  operation  can 

be  one  of  c,  m,  or  n.  Or  remove  the  tags  from  all  tagged  aliases. 

If  any  aliases  are  currently  tagged,  you  are  asked  if  the  tags  should  be  removed. 
Answer  y  to  remove  the  old  tags;  answer  n  to  keep  them.  In  either  case,  you  are 
prompted  for  a  string  to  match  in  either  the  alias  name  or  user  name  fields  of  each 
alias.  All  aliases  that  match  the  criterion  are  tagged.  If  you  enter  a  null  string 
(carriage-return  alone)  no  more  aliases  are  tagged. 

u  Undelete.  Remove  the  deletion  mark  from  the  current  alias.  See  also  d,  Ctrl-D,  and 

Ctrl-U. 

Ctrl-U  Undelete.  Remove  any  deletion  mark  from  all  messages  that  contain  a  specified  pat- 

tern in  the  From:  and  Subject:  header  entries.  See  also  d,  Ctrl-D,  and  u. 
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v  View.  Display  the  address-list  for  the  current  alias. 

x  Exit  from  the  alias  menu  without  processing  any  deletions.  Aliases  marked  for  dele- 

tion are  unmarked  andnewalias  is  not  run,  even  if  alias  additions  have  been  made. 

Alias  Index 

The  aliases  in  the  current  database  are  indexed  on  the  Alias  Menu,  one  per  line.  The  database  values  are 
defined  in  newalias(l). 

ssnum  fullname[,  comment]  type  [(S)]  alias 

defined  as: 

ss  A  two-character  status  field.  The  first  character  can  be: 

D     Delete.  The  alias  is  marked  for  deletion. 

N     New.  The  alias  is  new  or  changed  in  the  alias  text  file  but  is  not  included  in  the 
current  database.  Resynchronization  is  needed. 

Blank.  The  alias  is  in  the  current  database. 
The  second  character  can  be: 
+     Tag.  The  alias  is  tagged. 

Blank.  The  alias  is  not  tagged, 
num        The  index  number  of  the  alias. 

full  name  The  full  name  for  the  alias,  as  it  will  be  used  in  an  expanded  address.  It  has  the  form: 
firstname  lastname 

firstname  The  first  name,  from  the  alias  database. 

lastname  The  last  name,  from  the  alias  database, 
comment  Comment,  from  the  alias  database. 

type        Type  of  alias.  This  is  Person  for  an  alias  with  a  single  address  or  Group  for  an  alias  with 
two  or  more  addresses. 

(S)         If  present,  the  entry  is  from  the  elm  system  alias  database.  If  absent,  the  entry  is  from 
your  personal  alias  database. 

alias       Thealiasname.  If  the  record  has  multiplealias  names,  there  is  one  index  entry  per  name. 

Attachment  Configuration  Menu 

The  Attachment  Configuration  Menu  is  invoked  with  the  Attachment  Send  Menu  a  (add)  or  m  (modify) 
command.  The  menu  displays  the  default  or  current  specification  for  an  attachment.  If  it  is  called  with  the 
a  command,  it  automatically  prompts  for  a  file  name.  The  commands  are: 

d     Description.  The  value  is  placed  in  a  Content-Description :  body-part  header  entry.  The 
default  is  the  file  name. 

e     Content-Transfer-Encoding.  This  is  the  method  by  which  the  file  is  encoded  to  allow  it  to  pass 
through  various  Mail  Transport  Agents.  Thechoices  are: 

7bit       Unencoded,  normal  US-ASCII  text. 

8bit       Unencoded  8-bit  characters  with  the  high-order  bit  set. 

quoted-printable 

Text  with  control  characters  and  high-order-bit  characters  converted  to  a  string  in  the 
form  =hh,  where  hh  is  the  hexadecimal  representation  of  the  character.  An  =  at  the 
end  of  a  line  indicates  that  the  source  line  was  broken  into  two  lines. 

base64  Any  file  type  with  bits  encoded  in  6-bit  groups  and  rendered  in  numeric  order  as  the 
US-ASCII  characters  A-Z,  a-z,  0-9,  +,  and  /.  The  last  line  may  be  padded  to  a 
multipleof  4  characters  with  =  characters. 

binary  Unencoded  binary  data. 

The  value  is  placed  in  a  Content-Transfer-Encoding:  body-part  header  entry.  The 
default  is7bit. 
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f     Filename.  The  name  of  the  file  to  be  attached,  elm  examines  the  file  and  sets  the  values  of 
Content-Transfer-Encoding,  Content-Disposition,  and  Content-Type  accordingly. 

p     Content-Disposition.  The  value  is  placed  in  a  Content-Disposition :  body-part  header 
entry.  The  default  is  attachment;    filename=  filename. 

t     Content-Type.  The  type  of  thefileand  supporting  parameters,  intheform: 

type/subtype  [;  parameter]... 

The  type  can  be  one  of  application,  audio,  image,  message,  text,  or  video,  as 
defined  in  RFC  1521.  Although  multipart  is  also  a  valid  type,  you  cannot  specify  it  directly; 
elm  provides  it  as  necessary  and  handles  messages  that  contain  it.  The  value  is  placed  in  a 
Content-Type:  body-part  header  entry.  The  default  is: 

text/plain;  charset=US-ASCII 

Some  common  entries  are  described  below.  See  the  METAMAI L  CONFIGURATION  section  for 
additional  information. 

text/subtype  [;  charset=charset] 

This  is  relatively  readable  text  that  may  be  formatted  with  embedded  text  characters,  as 
for  possible  subtypes  richtext  or  html.  The  default  subtype  is  plain  (unformatted  in 
any  way).  The  default  charset  is  US-ASCII . 

application/ octet-stream 

This  is  a  catch-all  for  files  such  as  program  binary,  or  files  that  contain  control  characters  or 
characters  with  high-order  bits  set. 

application/postscript 

Thefilecan  be  displayed  with  a  PostScript-equipped  printer  or  viewer, 
message/ rf c822 

This  specifies  that  the  file  is  in  message  format,  as  described  in  the  Terminology  subsection, 
image/ jpeg,  image/gif 

Theseare  pi  dure  formats  that  requirea  display  program, 
audio/basic 

This  is  an  audioformat  that  requires  a  reproduction  program, 
video/mpeg 

This  is  an  audio/video  format  that  requires  a  reproduction  program. 
Attachment  Send  Menu 

The  Attachment  Send  Menu  is  invoked  with  the  Send  Menu  a  command.  This  menu  displays  a  list  of  the 
attachments  that  will  be  sent  in  a  message,  one  per  line,  as  described  in  the  Attachment  I  ndex  subsection. 

The  commands  are: 


a  Add  attachments.  Call  the  Attachment  Configuration  Menu  and  prompt  for  a  file 
name. 

d  Delete  an  attachment. 

e  Edit  an  attachment.  Call  the  editor  associated  with  the  attachment  if  it  is  editable, 

j  Move  the  current  attachment  pointer  down  to  the  next  attachment, 

k  Move  the  current  attachment  pointer  up  to  the  previous  attachment. 

Ctrl-L  Redraw  the  screen. 

m  Modify  the  attributes  of  an  attachment.  Call  the  Attachment  Configuration  Menu, 

p  Print  an  attachment.  See  the  Message  Menu  p  (print)  command, 

q  Quit.  Return  to  the  Send  Menu. 

s  Save  an  attachment.  See  the  Message  Menu  C  (copy)  command. 
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Attachment  View  Menu 

The  Attachment  View  Menu  is  invoked  with  the  Send  Menu  v  command.  This  menu  displays  a  list  of  the 
attachments  in  a  folder  message,  one  per  line,  as  described  in  the  Attachment  I  ndex  subsection. 

The  commands  are: 

Return  Display  the  current  attachment. 

j  Move  the  current  attachment  pointer  down  to  the  next  attachment, 

k  Move  the  current  attachment  pointer  up  to  the  previous  attachment. 

Ctrl-L  Redraw  the  screen. 

p  Print  the  attachment.  See  the  Message  Menu  p  (print)  command. 

q  Quit.  Return  to  the  previous  attachment  level  or  the  Message  Menu. 

s  Save  the  attachment.  The  attachment  is  saved  in  the  form  it  was  received,  as  with 

the  Message  Menu  s  (save)  command. 

v  View  the  subattachment  list,  if  any. 
Attachment  I  ndex 

Attachments  are  listed  on  the  Attachment  Send  Menu  and  the  Attachment  View  Menu  in  the  following  for- 
mat: 

num  filename  (size)  format  [encoding] 
defined  as: 

num  The  index  number  of  the  attachment, 

filename  The  name  of  the  attached  file. 

size  The  size  of  the  attachment  in  bytes,  computed  from  the  file  or  the  message. 

type/subtype   The  type  and  subtype  of  the  attachment.  This  value  is  placed  or  found  in  a 
Content-Type :  header. 

encoding         The  encoding  type.  This  value  is  placed  or  found  in  a  Content-Transfer- 
Encoding:  header. 

Header  Menu 

The  Header  Menu  is  invoked  with  the  Send  Menu  h  command.  It  allows  you  to  add,  change,  and  delete  a 
set  of  common  header  entries  in  your  message.  In  general,  if  an  item  is  empty,  it  is  not  included  in  the 
message. 

The  commands  are: 

Return  Return  to  Send  Menu. 

!  command      Shell.  Execute  command  with  the  shell  defined  by  the  shell  string  variable. 

a  Action:  header.  Enter  any  string.  If  this  entry  is  present  in  a  received  message, 

elm  displays  an  A  in  the  Permanent  Status  column  of  the  Message  I  ndex. 

b  Bcc:  header.  Enter  a  list  of  aliases  and  actual  addresses.  Aliases  are  expanded  and 

shown  as  addresses  and  user  names. 

c  Cc:  header.  Enter  a  list  of  aliases  and  actual  addresses.  Aliases  are  expanded  and 

shown  as  addresses  and  user  names. 

d  Domainize.  Convert  non-Internet  addresses  to  Internet  format.  The  UUCP  !  format 

(host .  domain  !  user)  becomes  the  I  nternet  @  format  (user@host .  domain).  If  .  domain 
is  omitted,  it  defaults  to  .uucp. 

e  Expires:  header.  Enter  any  numeric  value  from  1  to  56  (8  weeks).  If  this  entry  is 

present  in  a  received  message,  elm  displaysan  E  in  the  Variable  Status  column  of  the 
Message  I  ndex  when  the  computed  date  has  passed. 

i  In-Reply-To:  header.  Enter  a  string. 

n  Precedence:  header.  Enter  a  precedence  name.  If  the  precedences  string 

variable  is  set  and  nonnull,  the  name  must  be  one  defined  by  the  variable.  If  the 
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name  is  associated  with  a  priority,  and  the  Priority:  header  is  null,  the  priority 
value  is  inserted  in  the  Priority :  header.  If  precedences  is  null  or  not  set, 
you  can  enter  any  value. 

If  the  precedence  name  matches  one  defined  in  the  sendmail  configuration  file 
/etc/mail/sendmail .  cf ,  the  transmission  priority  is  modified  accordingly.  If 
there  is  no  match,  the  priority  is  not  changed. 

p  Priority:  header.  Enter  a  string.  If  this  entry  is  present  in  a  received  message, 

elm  displays  a  U  in  the  Permanent  Status  column  of  the  Message  I  ndex 

r  Reply-To:  header.  Enter  a  personal  alias  or  a  single  address.  If  it  is  present,  elm 

and  other  mailers  use  this  header  instead  of  the  From:  header  when  choosing  the 
address  for  a  reply  (Message  Menu  r  (reply)  command). 

s  Subject:  header.  Enter  a  string. 

t  To:  header.  Enter  a  list  of  aliases  and  actual  addresses.  Aliases  are  expanded  and 

shown  as  addresses  and  user  names. 

u  User-defined  header.  Define  your  own  header  entry  in  the  form: 

header-name:  header-string 

header-name:  must  not  contain  blanks.  You  can  use  this  command  to  create  a  Sen- 
sitivity: header  entry,  as  described  in  the  Message  Status  subsection,  or  a 
different  header,  but  only  one.  See  the  HEADER  FILE  section  for  another  way  to 
include  user-defined  header  entries. 


Options  Menu 

The  Options  Menu  is  invoked  with  the  Message  Menu  o  command.  It  displays  a  list  of  the  options,  defined 
by  the  conf  igoptions  string  variable,  that  you  can  modify  while  elm  is  running.  Enter  the  appropri- 
ate letter  (in  upper-  or  lowercase)  that  is  followed  with  a  right  parenthesis  () )  and  follow  the  directions  on 
the  screen.  The  full  set  of  option  prompts  and  the  corresponding  variables  is  listed  below.  The  default 
options  are  marked  with  an  *. 


A)  rrow  cursor 

B)  order  on  copy 

C)  alendar  file 

D)  isplay  mail  using 

E)  ditor  (primary) 

F)  older  directory 
H)old  sent  message 
J)    reply  editor 

K)  pause  after  pager 

A(l)ias  Sorting 

M) enu  display 

N)  ames  only 

O) utbound  mail  saved 

P)rint  mail  using 

R) eply  copies  msg 

S)orting  criteria 

T)ext  editor  (~e) 

U) ser  level 

V)  isual  Editor  (~v) 

W) ant  Cc :  prompt 

Y) our  full  name 

Z)   signature  dashes 


Thearrow  string  variable.  * 
Theprefix  string  variable. 
The  calendar  string  variable.  * 
Thepager  string  variable.  * 
Theeditor  string  variable.  * 
Themaildir  string  variable.  * 
The  copy  boolean  variable. 
Thealteditor  string  variable. 
Thepromptafter  boolean  variable. 
Thealiassortby  string  variable. 
Themenu  boolean  variable.  * 
Thenames  boolean  variable.  * 
Thesentmail  string  variable.  * 
Theprint  string  variable.  * 
Theautocopy  boolean  variable. 
The  sortby  string  variable.  * 
Theeasyeditor  string  variable. 
Theuserlevel  numeric  variable.  * 
The  visualeditor  string  variable.  * 
Theaskcc  boolean  variable. 
Thefullname  string  variable.  * 
Thesigdashes  boolean  variable. 


Note:  The  menu  displays  the  first  screen-height- 6  lines  from  the  defined  set.  screen-height  is  the  number 
of  text  lines  on  the  screen.  If  an  option  is  not  displayed,  it  cannot  be  modified. 

When  you  are  done,  enter  one  of  the  foil  owing  values: 

>  Save  the  current  configuration  values  in  your  configuration  file,  $HOME/ .  elm/elmrc.  If  the 
file  does  not  exist,  it  is  created.  This  is  a  convenient  way  to  make  an  configuration  file  that  you 
can  edit  directly,  as  well  as  with  the  Options  Menu. 
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i,l  Return  to  the  Message  Menu. 
q,Q  Return  to  the  Message  Menu. 

x,X  Exit  immediately  from  elm  without  changing  the  mailbox.  All  pending  changes  are  abandoned. 
Send  Menu 

The  Send  Menu  is  invoked  when  your  outbound  message  has  been  prepared  to  be  mailed  after  a  Message 
Menu  f ,  g,  m,  or  r  command  or  the  Alias  Menu  m  command. 

The  commands  are: 

Icommand  Shell.  Execute  a  shell  command.  See  the  Message  Menu  !  (shell)  command. 

a  Attachments.  I  nvoke  the  Attachments  Send  Menu. 

c  Copy.  Copy  to  a  file.  See  the  Message  Menu  C  (copy)  command. 

e  Edit.  I  nvoke  your  editor,  as  defined  by  the  alteditor  string  variable,  to  revise  the 

message. 

f  Forget.  Do  not  send  the  message.  At  user  levels  1  and  2,  the  message  may  be 

returned  to  the  send  buffer  when  you  execute  a  subsequent  Message  Menu  f ,  g,  m,  or 
r  command  or  the  Alias  Menu  m  command. 

h  Edit  the  header  entries.  I  nvoke  the  Header  Menu. 

m  Make  form.  Convert  the  message  to  the  forms  message  format.  See  the  FORMS 

MESSAGES  section.  This  command  is  only  avail  able  if  the  forms  boolean  variable  is 
ON  and  the  userlevel  numeric  variable  is  either  1  or  2. 

s  Send.  Send  the  message. 

FORMS  MESSAGES 

A  feature  that  is  unique  to  elm  isthe  ability  to  compose  and  reply  to  forms  messages. 

Creating  a  Forms  Message 

•  I  n  your  elmrc  file,  set  f  orms=ON. 

•  Set  your  userlevel  numeric  variableto  1  (moderately  experienced)  or  2  (expert).  You  can  do  this 
in  your  elmrc  file  or  on  the  default  Options  Menu. 

•  As  you  compose  the  message,  define  the  fields  to  be  filled  in  by  the  recipient  with  a  colon  (:),  followed 
by  either  the  number  of  spaces  allowed  for  the  field  value,  or  a  newline  to  indicate  that  the  field  may 
fill  the  remainder  of  the  line. 

A  colon  on  a  line  by  itself  indicates  that  the  recipient  will  be  prompted  for  multiline  input.  There  can 
be  no  blanks  before  the  colon. 

Every  line  containing  a  colon  is  a  prompt  line.  During  the  response  process,  all  text  starting  at  the 
first  nonblank  character  after  the  last  colon  on  each  line  is  deleted  and  the  line  is  evaluated  for 
response  fields. 

•  After  you  have  created  the  message,  enter  the  Send  Menu  m  (make  form)  command  to  set  up  the  spe- 
cial format.  Then  enter  the  Send  Menu  s  (send)  command  to  send  the  message. 

Here  is  an  example  of  a  simpleforms  message: 

On-Line  Phone  and  Address  Database 

Please  fill  out  and  return  as  soon  as  possible. 

Name : 

Manager : 

Department :  Division : 

Your  home  address : 

Home  phone  number : 

Thank  you  for  your  cooperation. 

Replying  to  a  Forms  Message 

When  you  receive  a  forms  message,  the  message  index  entry  is  flagged  with  an  F  status  letter.  You  can 
view  it  in  the  normal  way  with  the  Return  or  h  commands. 
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To  reply,  use  the  Message  Menu  r  (reply)  command  (you  cannot  use  the  Message  Menu  g  (group  reply) 
command),  elm  prompts  you  for  each  field,  with  any  text  present  between  the  fields  displayed  as  appropri- 
ate. The  example  above  is  presented  line-by-line;  user  input  isin  italictype: 

On-Line  Phone  and  Address  Database 

Please  fill  out  and  return  as  soon  as  possible. 

Name :  my  name 

Manager:  my  manager 

Department :  my  department 

Division:  my  division 

Your  home  address  :  home  address 

Home  phone  number :  phone  number 

Thank  you  for  your  cooperation. 

The  received  message  would  look  likethis: 

On-Line  Phone  and  Address  Database 

Please  fill  out  and  return  as  soon  as  possible. 

Name :   my  name 

Manager:   my  manager 

Department :    my  department  Division :    my  division 

Your  home  address :  home  address 
Home  phone  number :  phone  number 
Thank  you  for  your  cooperation. 

HEADER  FILE 

The  $HOME/  .  elm/elmheaders  file  provides  you  with  a  way  to  specify  special  information  headers  such 
as  X-Organization : ,  X-Phone: ,  and  so  forth.  The  nonblank  lines  from  this  file  are  added  to  the 
headers  of  all  outbound  mail. 

Entries  in  the  elmheaders  fileshould  have  the  foil  owing  format: 

header-name:  header-string 

header-name:  must  not  contain  blanks,  header-string  can  be  continued  over  several  lines  by  preceding 
each  continuation  line  with  blanks,  asindicated  by  the  output  below. 

Within  the  elmheaders  file,  you  can  use  backquotes  (left  apostrophes)  to  execute  shell  commands  when 
the  file  is  read,  so  that  an  entry  of  the  form: 

X-Operating-System:    'uname  -a 11 

would  produce  a  header  entry  like: 

X-Operating-System: 

HP-UX  hpulpcl7  B.10.10  A  9000/710  2012505939  two-user  license 

According  to  RFC  822,  user-defined  header  names  should  begin  with  X-  or  x-.  Otherwise,  they  risk  hav- 
ing their  usage  overridden  if  the  name  is  later  standardized  with  some  other  meaning. 

Defined  Headers 

The  foil  owing  header  names  are  defined  for  the  message  header  in  RFC  822  and  RFC  1521. 


Bcc : 

(822) 

Cc: 

(822) 

Comments : 

(822) 

Content -Description : 

(1521) 

Content-ID : 

(1521) 

Content-Transfer-Encoding : 

(1521) 

Content-Type : 

(1521) 

Date: 

(822) 

Encrypted: 

(822) 

From: 

(822) 

In-Reply-To : 

(822) 

Keywords : 

(822) 

MIME -Version : 

(1521) 

Message-ID : 

(822) 

Received: 

(822) 

References : 

(822) 

Reply-To : 

(822) 

Resent -Bcc : 

(822) 

Resent-Cc : 

(822) 

Resent -Date : 

(822) 

Resent -From : 

(822) 

Resent -Message-ID : 

(822) 

Resent -Reply-To : 

(822) 

Resent-Sender : 

(822) 

Resent-To : 

(822) 

Return-Path : 

(822) 

Sender : 

(822) 

Subject : 

(822) 

To: 

(822) 

X-user-def ined : 

(822) 
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Other  commonly  used  headers: 

Action : 

Content-Disposition : 
Expires : 
Newsgroups : 
Priority : 
Status : 


Apparent ly-To : 
Content-Length : 
Mailer : 
Precedence : 
Sensitivity: 
X-Mailer : 


ELM  CONFIGURATION 

elm  supports  user  configuration  by  means  of  the  $HOME/  .  elm/elmrc  configuration  file.  You  can  create 
the  configuration  file  with  the  Options  Menu  >  command.  It  can  contain  any  combination  of  the  string, 
numeric,  and  boolean  variables  described  below. 

String  Variables 

String  variables  have  the  form 

string-name  =  string-value 
The  foil  owing  string  variables  are  defined. 


aliassortby 


alteditor 


alternatives 


attribution 


calendar 


charset 


compatcharsets 


The  sort  order  for  the  alias  index  in  the  Alias  Menu.  The  recognized  values 
are: 

alias     Sort  by  alias  name. 

name      Sort  by  the  full  name  of  the  alias,  last  name  first, 
text      Sort  by  the  order  of  the  aliases  in  the  alias  text  file. 

Prefix  the  value  with  reverse-  to  reverse  the  sort  order.  The  default  is 
name. 

The  name  of  the  editor  to  use  for  messages  that  have  initial  text  (a  copied 
message  in  a  reply,  a  signature  in  any  outbound  message,  etc.).  when  the 
editor  string  variable  is  set  to  none  or  builtin.  The  default  is  the 
value  of  the  EDITOR  environment  variable,  if  set  and  nonnull,  or 
/usr/bin/vi  otherwise.  See  also  the  editor  string  variable. 

A  list  of  other  machine  and  user  name  combinations  that  you  receive  for- 
warded mail  from,  elm  uses  this  information  when  a  group  reply  is  being 
processed  to  ensure  that  a  reply  message  is  not  sent  to  a  user  and/or 
machine  address  that  would  simply  forward  the  reply  message  back  to  you. 
The  default  is  none. 

Attribution  string  for  replies.  When  you  reply  to  a  message  and  include  the 
message  in  the  reply,  this  string  is  placed  at  the  top  of  the  message.  The 
characters  %s  are  replaced  by  the  full  name  of  the  author  of  the  original 
message.  The  default  is  none.  For  example: 

attribution  =  %s  wrote: 

The  name  of  your  calendar  file.  This  is  used  in  conjunction  with  the  Mes- 
sage Menu  <  (calendar)  command,  which  scans  messages  for  calendar 
entries.  The  default  is  $HOME//calendar. 

The  name  of  the  character  set  used  with  the  MIME  Content-Type: 
header  for  the  text /plain  type.  It  can  beany  Internet-defined  charac- 
ter set  name  that  is  a  superset  of  US-ASCII .  The  default  is  US-ASCII . 
For  example, 

Content-Type:    text/plain;  charset=US-ASCII 

A  list  of  I  nternet-defined  character  sets  that  are  supersets  of  US-ASCI I ,  so 
that  messages  with  charset=US-ASCll  can  be  displayed  without  the 
helpof  metamail.  Thedefault  isa  string  containing  the  foil  owing  values: 

Extended_UNIX_Code_Packed_Format_f or_Japanese 

ISO-2022-JP 

ISO-8859-1 

ISO-8859-2 

ISO-8859-3 
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ISO-8859-4 

ISO-8859-5 

ISO-8859-7 

ISO-8859-8 

ISO-8859-9 

K0I8-R 

Shift_JIS 

conf  igoptions  A  string  of  options  that  can  be  configured  on  the  Options  Menu.  Specify  the 

options  as  a  single  letter  each,  in  the  order  they  should  be  displayed.  The 
default  is  "~_cdef  sopyv_am_un".  The  defaults  are  marked  below  with 
an  *. 

The  option  characters  include: 

A  The  menu  title. 

_  A  blank  line. 

a  Thearrow  string  variable.  * 

b  Theprefix  string  variable. 

c  The  calendar  string  variable.  * 

d  Thepager  string  variable.  * 

e  Theeditor  string  variable.  * 

f  Themaildir  string  variable.  * 

h  The  copy  boolean  variable. 

j  Thealteditor  string  variable. 

k  Thepromptafter  boolean  variable. 

1  Thealiassortby  string  variable. 

m  Themenu  boolean  variable.  * 

n  Thenames  boolean  variable.  * 

o  Thesentmail  string  variable.  * 

p  Theprint  string  variable.  * 

r  The autocopy  boolean  variable. 

s  The  sortby  string  variable.  * 

t  Theeasyeditor  string  variable. 

u  Theuserlevel  numeric  variable.  * 

v  The  visualeditor  string  variable.  * 

w  The askcc  boolean  variable. 

y  Thefullname  string  variable.  * 

z  The  sigdashes  boolean  variable. 

displaycharset  The  name  of  the  character  set  supported  by  the  display.  This  is  indepen- 
dent of  the  charset  string  variable.  This  is  also  copied  to  the 
MM_CHARSET  environment  variable  when  metamail  is  called.  The 
default  is  US-ASCII. 

easyeditor  The  name  of  the  editor  for  the  ~e  command  of  the  built-in  editor.  See  also 

theeditor  string  variable.  The  default  is  none. 

The  name  of  the  editor  to  use  when  creating  new  mail.  The  default  is  the 
value  of  the  EDITOR  environment  variable,  if  set  and  nonnull,  or 
/usr/bin/vi  otherwise. 

You  can  use  none  or  builtin  to  specify  the  built-in  editor.  The  built-in 
editor  is  availablefor  all  outbound  mail  that  does  not  already  have  text  in 
the  send  buffer  (no  forwarded  message,  no  copied  message  in  a  reply,  no 
signature  in  any  outbound  message,  etc.).  If  there  is  text  in  the  send  buffer 
and  builtin  is  specified,  the  editor  defined  by  the  alteditor  variable 
is  used  instead. 

See  also  the  alteditor,  easyeditor,  and  visualeditor  string 
variables. 

The  escape  character  used  in  the  built-in  editor.  The  default  is  tilde  (~). 

The  name  the  mailer  will  use  when  sending  mail  from  you.  The  default  is 
the  full  name  portion  (everything  up  to  the  first  comma)  of  thepw_gecos 
field  from  your  entry  in  the /etc/passwd  file.  This  field  can  beset  with 


editor 


escape 
f ullname 


HP-UX  Release  Hi:  December  2000 


-20- 


Section  1-223 


elm(l) 


elm(l) 


localsignature 


maildir 
pager 

precedences 


prefix 

print 
Section  1-224 


the  chf n  command  (see  chfn(l),  finger(l),  and  passwd(4)). 

A  signature  file  that  is  automatically  appended  to  outbound  mail  to  the 
local  host  before  the  editor  is  invoked.  This  usually  contains  personal  data 
about  the  sender.  See  also  the  remotesignature  string  variable.  The 
default  is  none. 

All  the  addresses  in  the  To :  header  must  be  apparently  for  the  local  host. 
Local  addresses  are  those  that,  after  any  elm  alias  conversion,  do  not  con- 
tain a  domain  name.  That  is,  they  have  only  a  user  name  (for  example, 
santaclaus)  or  a  user  name  and  the  local  host  name  (for  example, 
santaclausgnorthpole). 

santaclaus@northpole.arcticsea.org  is  considered  to  be  a 
remote  address,  even  if  it  points  to  the  local  host.  A  user  name  that  is 
readdressed  by  the  sendmail  system  alias  list  is  treated  as  local  if  it 
matches  the  preceding  criteria. 

Your  mail  directory,  where  you  usually  store  your  folders  for  received  and 
outbound  mail.  The  default  is  $HOME/ /Mail . 

In  elm,  you  can  use  the  =  metacharacter  to  specify  this  directory.  For 
example,  if  you  save  a  message  to  file  =/archive,  the  =  is  expanded  to 
the  current  value  of  maildir .  (The  slash  (/)  is  optional.) 

When  you  start  elm,  if  the  directory  specified  by  maildir  does  not  exist, 
you  are  asked  if  you  want  to  create  it.  If  you  answer  y  (yes),  the  directory 
is  created,  with  access  permissions  set  to  700. 

The  program  to  display  each  message.  The  default  is  the  value  of  the 
PAGER  environment  variable,  if  set  and  nonnull,  or  the  built-in  pager, 
builtin+,  otherwise. 

The  built-in  pager,  builtin+,  also  allows  you  to  execute  some  Message 
Menu  commands  whileyou  are  viewing  the  message  and  it  has  some  simple 
forward  and  backward  scrolling  commands.  While  it  is  active,  enter  ?  for  a 
list  of  commands.  An  alternativeisthemore  utility. 

A  list  of  precedence  values  that  you  can  place  in  a  Precedence :  header 
entry  in  outbound  mail,  using  the  Header  Menu.  Each  precedence  value 
can  be  optionally  paired  with  a  priority  value  that  is  automatically  placed  in 
a  Priority:  header  entry,  causing  the  received  message  to  be  marked 
as  urgent.  The  default  is  none. 

The  HP-UX  mail  transport  agent,  sendmail,  recognizes  this  header.  If 
the  precedence  value  is  defined  by  a  P  control  line  in  the  sendmail 
configuration  file,  /etc/mail/sendmail .  cf ,  the  transmission  priority 
of  the  message  is  adjusted  accordingly.  See  sendmail  (1M ). 

The  format  of  the  entry  is 

precedences  =  precedencef :  priority]  [precedencef:  priority]]  ... 

precedence  is  a  precedence  name.  The  default  list  defined  in 
/etc/mail/ sendmail .  cf  is: 

first-class  Transmission  priority  0,  the  default 

special-delivery  Transmission  priority  100 
list  Transmission  priority -30 

bulk  Transmission  priority -60 

junk  Transmission  priority -100 

priority  is  an  arbitrary  string  that  is  placed  in  a  Priority :  header  entry. 

The  prefix  for  an  included  line  in  an  outbound  message.  When  you  reply  to 
a  message  or  forward  a  message  to  another  person,  you  can  optionally 
include  the  original  message.  This  prefix  marks  the  included  line.  The 
default  is  >_  (the_  i s  i  nterpreted  as  a  space  character). 

Thecommand  to  run  when  thep  (print)  command  is  executed  from  various 
menus.  There  are  two  possible  formats  for  this  string:   If  the  string 
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receivedmail 
remotesignature 


savecharset 


sentmail 


shell 


sortby 


textencoding 
tmpdir 

visualeditor 
weedout 


contains  the  special  variable  %s,  the  variable  is  replaced  by  the  name  of  a 
temporary  file  that  contains  the  messages,  and  the  command  is  executed  by 
the  shell  defined  by  the  shell  string  variable.  If  the  string  does  not  con- 
tain %s,  the  temporary  file  name  is  appended  to  it,  and  the  command  is 
executed.  The  default  is 

cat  %s   |  lp 

The  file  where  the  received  messages  will  be  saved.  The  default  is 
=received,  the  file  received  in  the  directory  defined  by  maildir . 

A  signature  file  that  is  automatically  appended  to  all  outbound  mail  to 
remote  hosts  before  the  editor  is  invoked.  This  usually  contains  personal 
data  about  the  sender.  See  also  the  localsignature  string  variable. 
The  default  is  none. 

If  any  of  the  addresses  in  the  To:  header  entry  are  not  local,  as  described 
for  the  localsignature  string  variable,  the  remote  signature  file  is 
attached. 

The  character  set  to  be  used  to  save  a  message  in  a  folder.  Possible  values 
are  JIS,  SJIS,  and  EUC.  If  a  value  is  not  specified,  the  message  will  be 
saved  according  to  your  locale  (given  by  the  LC_TYPE  and/or  LANG 
environmental  variables).  This  option  is  applicable  only  for  the  Japanese 
locale.  The  default  is  none.  See  also  the  jisconversion  boolean  vari- 
able. 

Thefilewhere  copies  of  outbound  mail  can  besaved.  One  possibility  is  your 
incoming  mailbox,  /var/mail/ loginname.  The  default  is  =sent,  the 
file  sent  in  the  directory  defined  by  maildir. 

Seethe  copy  boolean  variablefor  further  details. 

The  shell  to  use  for  !  escapes  and  other  such  operations.  The  default  is  the 
value  of  the  SHELL  environment  variable,  if  set  and  nonnull,  or 
/usr/bin/ksh  otherwise. 

The  way  to  sort  the  index  of  the  current  folder.  The  choices  are: 
from 
sent 

received 
subject 


lines 
status 


The  name  of  the  sender. 

The  date  the  message  was  sent. 

The  date  the  message  was  received. 

The  subject  of  the  message.  A  leading  Re:  (and  some  oth- 
ers) is  ignored,  so  replies  sort  with  original  messages. 

The  number  of  lines  in  the  message. 

The  read  status:  blank,  O,  and  N. 


You  can  prefix  these  values  with  reverse-  to  reverse  the  order  of  the 
sort.  The  value  can  be  modified  on  the  Options  Menu.  The  default  is 
reverse-sent . 

Type  of  encoding  to  put  into  the  MIME  Content-Transfer- 
Encoding:  header  entry.  The  choices  are  7bit  or  8bit.  Thedefaultis 
7bit. 

Where  to  create  temporary  files.  The  default  is  the  value  of  the  TMPDIR 
environment  variable,  if  set  and  nonnull,  or  to  /tmp/  otherwise. 

Name  of  the  editor  to  use  for  the  ~v  command  of  the  built-in  editor.  The 
default  is  the  value  of  the  VISUAL  environment  variable,  if  set  and  non- 
null,  or  /usr/bin/vi  otherwise. 

A  list  of  header-entry  initial  strings  that  you  don't  want  to  see  when  you 
are  reading  mail.  This  list  is  made  effective  by  setting  the  weed  boolean 
variabletoON. 

The  list  can  continue  for  as  many  lines  as  desired,  as  long  as  the  continued 
lines  all  have  leading  blanks.  To  include  blanks  in  a  string,  enclose  it  in 
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quotation  marks  (").  The  strings  you  specify  are  normally  appended  to  the 
default  list,  which  is: 

>From 

Apparent ly-To : 

Content-Length 

Content-Transfer-Encoding 

Content-Type : 

From 

In-Reply-To : 
MIME -Version 
Mailer : 
Message-Id : 
Newsgroups : 
Received: 
References : 
Status : 
X-Mailer : 

There  are  two  special  values: 

*clear-weed-list* 

Clear  the  default  list.  The  default  headers  are  removed  from  the 
weedout  list,  allowing  you  to  completely  define  your  own  list. 

*end-of -user-headers* 

Mark  the  end  of  the  weedout  list,  in  case  any  following  lines  could 
be  mistaken  for  headers  in  the  list. 

The  default  value  of  weedout  is  *end-of -user-headers*. 

The  underscore  (_)  character  can  be  used  to  specify  a  space. 

Note  that  From  weeds  out  both  From  and  From:  .  If,  for  example,  you 
want  to  weed  out  From  but  not  From: ,  specify  *clear-weed-list* 
followed  by  From_  and  any  other  headers  that  you  don't  want  to  see. 


Numeric  Variables 

Numeric  variables  have  the  form 

numeric-name  =  numeric-value 
The  foil  owing  numeric  variables  are  defined. 


bounceback 


built inlines 


noencoding 


Threshold  for  returning  copies  of  remote  UUCP  messages.  If  the  destina- 
tion host  is  greater  than  the  specified  number  of  hops  (gateways)  from  your 
local  host,  the  destination  host  sends  you  a  copy  of  the  message  when  it  is 
received.  If  thevalueis  0,  this  feature  is  disabled.  The  default  is  0. 

Determines  if  the  built-in  pager  should  be  used  on  some  messages,  even  if 
you  usually  use  an  external  pager,  defined  in  the  pager  string  variable. 
There  are  two  ways  of  defining  whether  the  built-in  pager  should  be  used. 

•  If  you  want  to  use  the  built-in  pager  on  any  message  that  is  shorter  than 
n  lines,  set  the  value  to  n. 

•  If  you  want  to  use  the  built-in  pager  on  any  message  that  is  m  lines 
shorter  than  the  number  of  lines  on  your  screen,  set  the  value  to  -m. 

If  you  set  the  value  to  0,  the  message  will  always  be  sent  through  the 
external  pager.  The  default  is -3. 

This  enables  you  to  send  raw  8-bit  or  binary  data  when  the  mail  transfer 
agent  doesn't  support  the  8BITMIME  and  the  -B8BITMIME  options.  The 
default  is  0. 

The  possible  values  are: 

0     Always  convert  8-bit  and  binary  messages  to  7-bit  before  sending 
them. 
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readmsginc 

sleepmsg 

timeout 
userlevel 


1  Convert  8-bit  messages  to  7-bit,  but  depend  on  sendmail  to  handle 
binary  messages. 

2  Depend  on  sendmail  to  handle  both  8-bit  and  binary  messages. 

The  value  by  which  the  Reading  in  folder,  message:  counter  is 
incremented  while  reading  a  new  folder.  If  you  set  this  value  to  a  number 
larger  than  one,  it  will  speed  up  the  time  it  takes  to  read  a  large  folder 
when  you  areusinga  slow  terminal.  Thedefault  is  1. 

The  time  in  seconds  that  elm  will  wait  after  displaying  a  diagnostic  mes- 
sage before  erasing  it.  The  value  can  be  0  or  a  positive  integer.  The 
default  is  2. 

The  interval,  in  seconds,  after  which  elm  rechecks  the  incoming  mailbox 
for  new  mail.  Thedefault  is  600  (10  minutes). 

The  relative  level  of  your  user  sophistication.  Acceptable  values  are: 

0  Novice  user  (the  default).  Command  menus  are  a  small  verbose  sub- 
set of  the  availablecommands. 

1  Moderately  experienced  user.  Command  menus  are  a  larger  terse 
subset  of  the  available  commands.  Outbound  message  commands 
allow  you  to  recover  previously  unsent  messages  as  the  text  of  the 
current  outbound  message. 

2  Expert.  The  features  are  the  same  as  for  1. 

Level  1  or  2  is  required  if  you  want  to  send  a  forms  message. 


Boolean  Variables 

Boolean  variables  have  the  forms 

boolean-name  =  ON   -and-   boolean-name  =  OFF 
Thefollowing  boolean  variablesare defined. 


alwaysdelete 


alwayskeep 


alwaysstore 


ask 


If  ON,  the  default  answer  of  the  Message  Menu  q  (quit)  prompt 

Delete  messages?  (y/n) 

is  set  to  y  (yes).  If  OFF,  the  default  answer  is  set  to  n  (no).  The  default  is 
OFF.  See  the  Message  Menu  q  command. 

If  ON,  the  default  answer  of  the  Message  Menu  q  (quit)  prompt 

Keep  unread  messages   in  incoming  mailbox?  (y/n) 

is  set  to  y  (yes).  If  OFF,  the  default  answer  is  set  to  n  (no).  The  default  is 
ON.  See  the  Message  Menu  q  command. 

If  ON,  the  default  answer  of  the  Message  Menu  q  (quit)  prompt 

Move  read  messages  to  "received"   folder?  (y/n) 

is  set  to  y  (yes).  If  OFF,  the  default  answer  is  set  to  n  (no).  The  default  is 
OFF.  See  the  Message  Menu  q  command. 

If  ON,  use  an  arrow  (->)  to  mark  the  current  item  in  a  menu  index.  If 
OFF,  use  an  inverse  bar.  If  the  program  is  invoked  with  the  -a  command 
lineoption,  arrow  issettoON.  Thedefault  is  OFF. 

If  ON,  you  are  asked  the  questions 

Delete  messages?  (y/n) 

Move  read  messages  to  "received"   folder?  (y/n) 
Keep  unread  messages   in  incoming  mailbox?  (y/n) 

(as  appropriate)  each  time  you  leave  the  program  with  the  Message  Menu  q 
(quit)  command.  See  that  command  for  details  of  the  process.  If  OFF,  or  if 
you  use  the  Message  Menu  Q  command,  elm  uses  the  values  defined  by  the 
alwaysdelete,  alwaysstore,  and  alwayskeep  boolean  variables, 
respectively,  without  prompting.  Thedefault  is  ON. 
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If  ON,  elm  prompts  you  for  "carbon  copies"  with  the  prompt  Copies  To : 
each  time  you  send,  forward,  or  reply  to  a  message.  If  OFF,  the  prompt  is 
omitted.  In  either  case,  you  can  still  explicitly  include Cc:  addresses  with 
the  ~c  command  in  the  built-in  editor,  or  with  the  Header  Menu  com- 
mands. The  default  is  ON. 

If  ON,  elm  automatically  copies  the  text  of  the  message  you  are  replying  to 
into  the  edit  buffer.  If  OFF,  elm  prompts  you  with  Copy  message?. 
The  default  is  OFF. 

If  ON,  you  are  asked  to  confirm  before  messages  are  appended  to  an  exist- 
ing file,  whether  it  is  a  file  in  your  mail  directory  or  a  file  in  another  direc- 
tory. If  OFF,  see  conf irmappend  and  confirmfiles  Operation 
below.  The  default  is  OFF. 

If  ON,  you  are  asked  to  confirm  before  a  new  file  is  created,  whether  it  is  a 
file  in  your  mail  directory  or  a  file  in  another  directory.  If  OFF,  see  con- 
firmcreate  and  conf irmf olders  Operation  below.  The  default  is 
OFF. 

If  ON,  you  are  asked  to  confirm  before  messages  are  appended  to  an  exist- 
ing file  that  is  not  in  your  mail  directory.  This  does  not  affect  files  in  your 
mail  directory.  If  OFF,  see  conf  irmappend  and  confirmfiles 
Operation  below.  The  default  is  OFF. 

conf  irmf  olders  If  ON,  you  are  asked  to  confirm  before  a  new  file  is  created  in  your  mail 
directory.  This  does  not  affect  files  in  other  directories.  If  OFF,  see  con- 
firmcreate  and  conf  irmf  olders  Operation  below.  The  default  is 
OFF. 

conf  irmcreate  and  conf  irmf  olders  Operation 

conf irmcreate=ON  and  conf irmf olders=ON 

Confirm  before  creating  a  file  in  your  mail  directory. 
Confirm  before  creating  a  file  another  directory. 

ON  and  OFF  Confirm  before  creating  a  file  in  your  mail  directory. 
Confirm  before  creating  a  file  another  directory. 

OFF  and  ON  Confirm  before  creating  a  file  in  your  mail  directory.  Do 
not  confirm  before  creating  a  file  another  directory. 

OFF  and  OFF   Do  not  confirm  before  creating  a  file  in  your  mail  directory. 

Do  not  confirm  before  creating  a  file  another  directory. 

conf  irmappend  and  confirmfiles  Operation 

conf irmappend=ON  and  conf irmf iles=ON 

Confirm  before  appending  to  a  file  in  your  mail  directory. 
Confirm  before  appending  to  a  file  in  another  directory. 

ON  and  OFF     Confirm  before  appending  to  a  file  in  your  mail  directory. 

Confirm  before  appending  to  a  file  in  another  directory. 

OFF  and  ON     Confirm  before  appending  to  a  file  in  your  mail  directory. 

Do  not  confirm  before  appending  to  a  file  in  another  direc- 
tory. 

OFF  and  OFF  Do  not  confirm  before  appending  to  a  file  in  your  mail  direc- 
tory. Do  not  confirm  before  appending  to  a  file  in  another 
directory. 

copy  If  ON,  save  si  lent  copies  of  all  outbound  mail  on  the  outbound  step.  If  OFF, 

do  not  save  copies.  The  default  is  OFF. 

If  ON,  and  the  savename  boolean  variable  is  ON,  elm  first  tries  to  save  it 
to  a  file  named  as  defined  by  savename .  If  the  file  exists,  the  message  is 
saved.  If  the  file  does  not  exist,  but  the  forcename  boolean  variable  is 
ON,  the  file  is  created  and  the  message  is  saved.  If  f  orcename=OFF,  the 
message  is  saved  to  the  file  defined  by  the  sentmail  string  variable.  If 
savename=OFF ,  the  message  is  saved  to  the  file  defined  by  the 


askcc 


autocopy 


conf irmappend 


conf irmcreate 


confirmfiles 
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f orcename 
forms 

jisconversion 

keepempty 
keypad 

menu 
metoo 

mime forward 
movepage 


nohdrencoding 
noheader 

noheaderfwd 

pagemultipart 

pointnew 

promptafter 
resolve 


sentmail  string  variable. 

If  ON,  create  the  folder  when  saving  outbound  messages  by  the  login  name 
of  the  recipient,  even  if  the  folder  doesn't  already  exist.  If  OFF,  do  not 
create  the  folder.  The  default  is  OFF. 

Seethe  copy  boolean  variablefor  further  details. 

If  ON,  and  the  userlevel  numeric  variable  is  1  or  2,  you  can  create  a 
forms  message.  The  Send  Menu  m  (make  form)  command  converts  your 
message  i nto  a  forms  message.  If  OFF,  you  cannot.  The  default  is  ON. 

If  ON,  convert  outbound  mail  to  J  IS  (J  apanese  Industrial  Standard)  before 
sending  it.  If  OFF,  do  not  convert  it.  This  option  is  applicable  only  to  the 
J  apanese  locales,  ja_JP .  S  JIS  and  ja_JP .  eucJP  .  The  default  is  OFF. 
savecharset  string  variable. 

If  ON,  keep  folders  from  which  all  the  messages  are  deleted.  If  OFF,  delete 
empty  folders.  The  default  is  OFF. 

If  ON,  enabletheHP  2622  terminal  cursor  keys.  If  OFF,  disable  the  cursor 
keys.  If  the  program  is  invoked  with  the  -K  command  line  option, 
keypad  is  set  to  OFF.  See  also  the  softkeys  boolean  variable.  The 
default  is  ON. 

If  OFF,  this  inhibits  the  menu  display  on  all  program  screen  displays.  If 
ON,  the  menus  are  displayed.  If  the  program  is  invoked  with  the  -m  com- 
mand lineoption,  menu  issettoOFF.  The  default  is  ON. 

If  ON,  you  are  sent  a  copy  of  the  message  that  you  send  to  an  alias  that 
includesyour  namealso.  If  OFF,  the  copy  is  not  sent.  The  default  is  OFF. 

If  ON,  a  forwarded  message  is  sent  as  an  attachment.  If  OFF,  a  forwarded 
message  is  sent  as  part  of  the  main  message.  Thedefault  isON. 

If  ON,  commands  that  move  through  the  mailbox  by  pages  (the  +  and  - 
commands)  also  move  the  current  index  pointer  to  the  top  of  the  new  page 
of  messages.  If  OFF,  moving  through  the  pages  does  not  alter  the  current 
message  pointer  location.  Thedefault  is  ON. 

If  ON,  show  only  the  user  names  when  expanding  the  To:  aliases  for  an 
outbound  message.  If  OFF  ,  show  the  entire  expanded  addresses.  The 
default  is  ON. 

If  ON,  don't  do  RFC  1522  encoding  for  header  values  that  contain  8-bit  or 
multi  byte  characters.  If  OFF,  do  the  encoding.  Thedefault  is  OFF. 

If  ON,  do  not  include  the  headers  of  messages  when  copying  a  message  into 
a  file  buffer  for  replying  to  or  forwarding.  If  OFF,  copy  all  headers.  The 
default  is  ON. 

If  ON,  do  not  include  headers  when  copying  a  message  into  a  file  buffer  for 
forwarding.  If  OFF,  copy  all  headers.  For  forwarding,  this  option  overrides 
the  setti  ng  of  noheader .  Thedefault  isOFF. 

If  ON,  use  the  value  of  the  pager  variable  to  display  MIME  multipart 
messages  with  unknown  subparts  or  with  unknown  subtypes.  If  OFF,  call 
metamail  to  view  multipart  messages.  Thedefault  is  OFF. 

If  ON,  automatically  point  to  the  first  new  message  in  your  message  index 
at  start-up.  If  OFF,  point  to  the  first  message.  I  n  either  case,  if  the  start- 
up folder  is  not  your  incoming  mailbox,  or  if  there  are  no  new  messages, 
point  to  the  first  message.  Thedefault  is  ON. 

If  ON,  prompt  for  a  command  after  the  external  pager  exits.  If  OFF,  return 
to  the  calling  menu.  Thedefault  is  ON. 

If  ON,  move  the  pointer  to  the  next  message  in  the  index,  after  deleting, 
undeleting,  saving,  or  forwarding  a  message.  If  OFF,  keep  the  pointer  at 
the  current  message.  The  default  is  ON. 
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savename  If  ON,  and  you  are  saving  a  message,  elm  constructs  a  suggested  file  name 

in  your  maildir  directory  from  the  user  name  of  the  person  who  sent  the 
message,  in  the  form  =username.  If  OFF,  no  file  name  is  suggested. 

If  ON,  and  you  are  sending  a  message  that  will  be  saved,  elm  constructs  a 
file  name  based  on  the  user  name  of  the  first  entry  in  the  To:  list,  in  the 
same  form  as  above.  If  OFF,  no  file  name  is  constructed.  See  the  copy 
boolean  variablefor  further  details. 

The  default  is  ON. 

sigdashes  If  ON,  insert  two  dashes  above  the  signature  text,  included  from  a  local  or 

remote  signature  file.  This  is  a  common  convention.  If  OFF,  omit  the 
dashes.  The  default  is  ON. 

If  ON,  enablethe  HP  2622  terminal  function-key  protocol.  If  OFF,  disable 
the  function-key  protocol.  If  the  program  is  invoked  with  the  -k  or  -K 
command  line  option,  softkeys  is  set  to  OFF.  See  also  the  keypad 
boolean  variable.  The  default  is  OFF. 

If  ON,  title  a  displayed  message  with  a  line  in  the  form: 

Message  number/total  sendername      date  time 

sendername,  date,  and  time  are  extracted  from  the  message  headers  in  the 
manner  described  in  Message  I  ndex.  This  is  useful  if  you  have  suppressed 
the  relevant  header  entries  with  the  weedout  list.  If  OFF,  the  message  is 
not  titled.  The  default  is  ON. 

If  ON,  use  the  termcap  ti/te  and  terminfo  cup  cursor-positioning 
entries  (see  terminfo(4)).  If  OFF,  do  not  use  those  entries.  Iftheprogram 
is  invoked  with  the -t  command  line  option,  usetite  is  set  to  OFF.  The 
default  is  ON. 

If  ON,  do  not  display  the  headers  defined  by  weedout  variable  when 
displaying  a  message  for  reading.  If  OFF,  display  all  headers.  Thedefault 
is  ON. 


softkeys 


titles 


usetite 


weed 


METAMAIL  CONFIGURATION 

MIME  (Multipurpose  I  nternet  Mail  Extensions)  encoding  classifies  the  message  and  its  attachments  accord- 
ing to  a  Content-Transfer-Encoding,  which  is  the  encoding,  if  any,  that  is  used  to  make  the  message  mail- 
able, and  a  Content-Type,  which  is  the  type  and  form  of  the  message  part  after  it  has  been  decoded.  The 
encoding  and  types  are  described  in  more  detail  in  the  Attachment  Configuration  Menu  subsection  and  in 
RFC  1521. 

elm  provides  built-in  support  for  the  following  Content-Types: 

text/plain  [;  charset=charset] 

The  text  is  all  in  the  displayablecharacter  set  charset  which  defaults  to  US-ASCII . 

multipart /mixed  ;  boundary=boundary-string 

The  message  is  composed  of  a  number  of  individual  "body  parts",  separated  by  — boundary- 
string,  each  having  optional  headers  defining  Content-Type  and  Content-Transfer-Encoding.  The 
default  Content-Type  is  text/plain . 

multipart/digest  ;  boundary=boundary-string 

This  is  similar  to  multipart  /mixed,  except  that  the  default  Content-Type  is 
message/rfc822. 

multipart/report  ;  boundary=boundary-string 


message/ rf c822 

The  message  consists  of  another  message  in  standard  message  format. 

metamail  is  a  system  program  that  is  invoked  by  elm  to  manage  the  display  of  messages  and  attach- 
ments that  are  not  displayablein  ordinary  ASCI  I  text. 

Section  1-230  -  27  -  HP-UX  Release  Hi :  December  2000 


elm(l) 


elm(l) 


metamail  provides  external  support  for  other  Content-Types,  as  defined  in  one  or  more  mailcap  files. 
The  system  mailcap  file  is  /etc/mail/mailcap.  You  can  define  your  own  default  mailcap  file  in 
$HOME/ .mailcap.  You  can  also  specify  your  own  list  of  mailcap  files  by  setting  the  MAILCAPS 
environment  variable.  The  mailcap  files  are  searched  in  order  until  an  entry  is  found  that  matches  the 
Content-Type  and  any  qualifications. 

A  minimum  mailcap  entry  consists  of  a  line  in  the  form: 

content-type  ;  command 

The  command  is  the  command  that  you  would  type  to  view  a  file  of  the  indicated  Content-Type,  with  the 
string  %s  replaced  by  a  file  name.  For  example,  to  view  body  part  that  was  HTML  source  text  and  had  the 
Content-Type  text /html,  you  could  have  the  entry 

text/html;    netscape  %s 

Similarly,  for  a  Gl  F  image  file,  you  could  have  the  entry 

image/gif;    xv  %s 

RFC  1521  defines  a  number  of  Content-Types  that  elm  leaves  for  metamail  to  handle: 

text/richtext 

multipart/alternative 

multipart /parallel 

multipart/digest 

mess age /partial 

message/external-body 

image/ jpeg 

image/gif 

audio/basic 

video/mpeg 

application/ octet-stream 
application/postscript 

Check  the  system  mailcap  file  for  entries  that  handle  many  of  them. 

EXTERNAL  INFLUENCES 
Environment  Variables 

HOME  Your  home  (login)  directory. 

EDITOR         If  set  and  nonnull,  provides  a  default  value  for  the  alteditor  and  editor  string  vari- 
ables. 

LANG  If  set  and  nonnull,  determines  the  language  in  which  messages  are  displayed.  The  default 

isc.  See  environ (5). 

MAILCAPS      If  set,  defines  the  search  path  for  mailcap  files  used  by  metamail .  The  default  is 

$HOME/ . mailcap : / etc/mail/mailcap 
PAGER  If  set  and  nonnull,  provides  a  default  value  for  the  pager  string  variable. 

SHELL  If  set  and  nonnull,  provides  a  default  value  for  the  shell  string  variable. 

TMPDIR         If  set  and  nonnull,  provides  a  default  value  for  the  tmpdir  string  variable. 
VISUAL         If  set  and  nonnull,  provides  a  default  value  for  the  visualeditor  string  variable. 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

EXAMPLES 

Message  Mode  Example 

To  send  a  message  without  loading  the  main  elm  mail -processing  program,  use  the  simple  command  form 
consisting  of  the  name  of  the  program  followed  by  the  recipient's  login  name  and  optional  address,  elm 
prompts  for  subject  and  copies,  then  starts  an  editor  so  you  can  compose  the  message  (user  responses  are  i  n 
italic  type): 

$  e!mj_doe 

To:  doe   (John  Doe) 
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Subject:   this  is  a  test 
Copies  To:  ... 

...invokes  editor,  you  compose  message,  then... 
Your  options  now  are : 

a) ttachments  e)dit  message  edit  h)eader  s)end  it  f)orget  it. 

What  is  your  choice?  S 
mail  sent ! 

If  you  "forget"  the  message,  it  issaved  in  $HOME/Canceled.mail. 

File  Mode  with  Redirection 

To  send  a  file  by  use  of  command-line  redirection,  use  a  command  like: 

$  elm  j_doe  <  help . c 
which  reads  filehelp .  c  and  sends  it  with  the  default  subject. 

File  Mode  with  a  Pipe 

To  mail  the  output  of  a  command  and  includea  subject  line: 

$  Is  -a   |   elm  -s  "Directory  Listing"  j_doe 


WARNINGS 

Using  two  separate  mail  programs  to  access  the  same  mail  file  simultaneously  (usually  inadvertently  from 
two  sepa rate  wi  n dows)  can  cau se  u n predi  ctabl  e  resu I ts. 


AUTHOR 

elm  was  developed  by  Hewlett-Packard  Company. 


FILES 

$HOME/ .elm 

$  HOME / . elm/aliases 
$HOME/ . elm/aliases . dir 
$  HOME / . elm/ aliases . pag 
$HOME/ . elm/aliases . text 
$  HOME / . elm/elmheaders 
$HOME/ . elm/elmrc 
$HOME/Canceled . mail 
/tmp/alias .  pid 
/tmp/form.  pid 
/tmp/mbox.  loginname 
/tmp/print .  pid 
/tmp/snd.  pid 
/tmp/sndh.  pid 

/usr/lib/nls/msg/C/elm. cat 
/usr/ share/lib/ elm/ elmrc-inf o 
/var/mail 

/var/mail/ . elm 
/var/mail/ . elm/aliases 
/var/mail/ . elm/ aliases . dir 
/var/mail/ . elm/aliases .pag 
/var/mail/ . elm/ aliases . text 
/var/mail/  loginname 

/var/mail/  loginname.  lock 


Directory  for  the  user's  elm  alias,  configuration,  header, 
and  other  files 

U  ser  al  i  as  database  data  tabl  e 

User  alias  database  directory  table 

U  ser  al  i  as  database  hash  tabl  e 

U  ser  a  I  i  as  sou  rce  text 

User-defined  additional  headers 

User  configuration  file 

Canceled  message  in  noninteractive  use. 

Temporary  filefor  deleting  alias 

Editor  buffer  for  forms  message 

Temporary  mailbox  for  user  logname 

Temporary  filefor  printing  message 

Outgoing  mail  message  edit  buffer 

Outgoing  mail  header  edit  buffer 

Location  of  the  message  catalog 

Comment  filefor  $HOME/  .  elm/elmrc  file 

Directory  for  incoming  mail; 

it  must  have  mode  755  and  group  I D  mail 

Directory  for  elm  mailer  system  aliases 

System  alias  database  data  table 

System  alias  database  directory  table 

System  alias  database  hash  table 

System  al  i  as  source  text 

I  ncomi  ng  mai  I  box  for  user; 

it  must  have  mode  660  and  group  I D  mail 

Lock  for  mail  directory 


SEE  ALSO 

answer(l),  chfn(l),  elmalias(l),  fastmail(l),  finger(l),  mailfrom(l),  newalias(l),  newmail(l),  readmail(l), 
vi(l),  sendmail(lM),  passwd(4),  terminfo(4),  environ(5). 

RFC  821  "Simple  Mail  Transfer  Protocol  (SMTP)" 
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RFC  822  "Standard  for  the  Format  of  I  nternet  Text  Messages" 

RFC  1521  "MIME  (Multipurpose  Internet  Mail  Extensions)  Part  One:   Mechanisms  for  Specifying  and 
Describing  the  Format  of  I  nternet  Message  Bodies" 

RFC  1522  "MIME  (Multipurpose  Internet  Mail  Extensions)  Part  Two:  Message  Header  Extensions  for 
Non-ASCII  Text" 
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NAME 

elmalias-  display  and  verify  elm  user  and  system  aliases 
SYNOPSIS 

elmalias  [-dersu]  [-a|-f  format  | -n  | -v  | -V]  [alias-name-list] 
Remarks 

The  former  functionality  of  the  elmalias  command  has  been  taken  over  by  the  newalias  command 
(see  newalias(l)). 

DESCRIPTION 

The  elmalias  command  displays  and  verifies  user  and  system  elm  aliases. 

The  system  database  must  have  been  created  by  the  newalias  command  (see  newalias(l)).  The  user 
database  must  have  been  created  by  either  the  newalias  command  or  the  elm  mail  system  (see  elm(l)). 
If  the  same  alias  is  in  both  databases,  the  user  version  is  used.  Missing  database  files  are  silently  ignored. 

Each  database  entry  can  have  the  foil  owing  fields,  which  are  described  in  detail  in  newalias(l): 

alias-list         A  list  of  one  or  more  aliases  for  the  entry. 

address-list  A  list  of  one  or  more  addresses  for  the  entry.  An  address  can  be  an  alias  from  another 
entry's  alias-list. 

comment  An  optional  field  containing  information  about  the  entry.  This  field  is  not  included  in 
outbound  mail. 

firstname  An  optional  field  interpreted  as  the  first  name  of  the  person  or  group.  It  is  used  in 
full  name. 

lastname  An  optional  field  interpreted  as  the  last  name  of  the  person  or  group.  It  is  used  in 
full  name. 

fullname  A  combination  value  made  up  from  the  firstname  and  lastname  fields,  in  the  form: 
firstname  lastname. 

elmalias  recognizes  three  types  of  alias  names: 

person  A  database  entry  that  has  one  address  in  address-list,  elmalias  assumes  this 
address  is  a  valid  mailing  address. 

group  A  database  entry  that  has  two  or  more  addresses  in  address-list,  elmalias 

assumes  initially  that  these  addresses  are  aliases  to  person  or  group  entries. 

unknown  An  address  in  a  group  entry  or  an  alias  in  alias-name-list  that  is  not  an  alias  in  the 
database.  In  both  cases,  the  item  is  reported  as  both  the  alias  name  and  its  address. 

With  no  options  or  operands,  elmalias  displays  the  address-list  field  for  each  alias  in  the  two  databases. 
If  an  entry  has  more  than  one  alias,  the  address-list  field  is  displayed  multiple  times. 

With  an  alias-name-list  and  no  options,  elmalias  displays  the  address-list  field  of  each  alias  name  in  the 
list.  If  an  alias  name  is  not  found  in  the  databases,  it  is  treated  as  unknown,  without  comment. 

Options 

elmalias  recognizes  the  following  options: 

-a  Change  the  display  to  alias  name  foil  owed  by  address-list  field, 

-d  Turn  debugging  on. 

-e  Fully  expand  group  aliases.  This  option  can  be  used  only  when  an  alias-name-list  is 

given. 

If  an  address  in  a  group  address  list  is  an  alias  name,  it  is  replaced  by  that  alias 
entry.  The  process  is  recursive  until  the  results  are  either  person  or  unknown 
types.  If  a  group  address  is  not  an  alias  name,  it  is  reported  as  both  the  alias  name 
and  the  address,  with  type  unknown.  Duplicate  alias  names  are  reported  only  once, 
person  entries  are  not  expanded,  even  if  their  addresses  are  actually  aliases. 

-f  format  Display  the  format  stringfor  each  aliasnamein  thefileor  in  the  alias-name-list.  The 
following  character  pairs  are  replaced  in  the  format  by  the  corresponding  value  for 
each  alias. 
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%a  The  alias  name. 

%c  The  comment  field. 

%1  The  lastname  field. 

%n  Thefullnamevalue. 

%t  Thealiastype:  person,  group,  or  unknown. 

%v  The  address-list  field. 


-n  Change  the  display  to  address-list  foil  owed  byfullname,  if  any,  in  parentheses. 

-r  Report  an  error  if  a  name  in  alias-name-list  does  not  correspond  to  an  alias  in  the 

database.  Display  a  message  for  each  unknown  nameand  exit  with  a  nonzero  status. 

-s  Usethesystem  alias  databaseonly,  unless -u  is  also  specified. 

-u  Usethe  user  alias  databaseonly,  unless -s  is  also  specified. 

-v  Use  a  verbose  output  format.  Change  the  display  to  alias  name,  followed  by  address- 

list,  followed  byfullname,  if  any,  in  parentheses. 

-V  Use  a  very  verbose,  multiline  output  format  with  the  following  titles,  corresponding  to 


the  format  codes  of  the  -f  option.  If  a  field  is  empty,  the  title  is  omitted. 

Alias : 
Address : 
Type: 
Name : 

Last  Name : 
Comment : 

EXIT  STATUS 

elmalias  sets  the  foil  owing  exit  status  values: 

0  Normal  completion. 
<>0  An  error  occurred.  You  may  have  specified: 

•  An  invalid  option. 

•  The-e  option  without  an  alias-name-list. 

•  The  -f  option  without  a  format. 

•  The-r  option  with  an  unknown  alias namein  alias-name-list. 

EXAMPLES 

Consider  a  user  database  that  contains  the  foil  owing  entries: 
#  sample  alias  file 

mom  =  My  Mommy,   Work:   x2468  =  my _mother@a . computer 

dad, father, pop  =  Father;    Dear,   Work:   xl357  =  host ! otherhost ! dad 

parents  =  The  Folks  =  mom  dad  parentghost 

siblings  =  The  Kids  =  brotherl 

brother2 

sister 

brotherl  =  Son;   First  =  brolgkid . computer 

Sincebrother2  and  sister  do  not  refer  to  alias  entries,  they  are  typed  as  unknown . 

elmalias  with  no  options  or  operands  produces  the  following  output. 

my_mother@a . computer 
host ! otherhost ! dad 
host ! otherhost ! dad 
host ! otherhost ! dad 
mom, dad, parentghost 
brotherl , brother2 , sister 
brolgkid . computer 

elmalias  -v  produces  the  alias  names,  address,  and  full  name,  as  follows: 
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mom 
dad 
father 
pop 

parents 

siblings 

brotherl 


my _mother@a . computer   (My  Mommy) 
host ! otherhost ! dad  (Dear  Father) 
host ! otherhost ! dad   (Dear  Father) 
host ! otherhost ! dad  (Dear  Father) 
mom, dad, parent@host   (The  Folks) 
brotherl , brother2 , sister   (The  Kids) 
brol@kid . computer   (First  Son) 


To  expand  a  set  of  aliases  and  format  them  with  field  titles,  use  the  - 
command: 


•e  and  -f  options,  as  in  the  following 


elmalias  -ef  "Alias : 

producing: 


ia     Address:    %v     Type:    %t"  parents  siblings 


Alias:  mom    Address:   my _mother@a . computer     Type:  Person 

Alias :  dad    Address :   host ! otherhost ! dad    Type :  Person 

Alias:  parentghost     Address:   parent@host     Type:  Unknown 

Alias:  brotherl     Address:   brolgkid . computer     Type:  Person 

Alias :  brother2     Address :   brother2     Type :  Unknown 

Alias :  sister     Address :    sister     Type :  Unknown 

AUTHOR 

elmalias  was  developed  by  HP. 


FILES 

$  HOME / . elm/aliases 
$HOME/ . elm/aliases . dir 
$HOME/ . elm/aliases . pag 
$HOME/ . elm/aliases . text 
/var/mail/ . elm/aliases 
/var/mail/ . elm/ aliases .  dir 
/var/mail/ . elm/aliases .pag 
/var/mail/ . elm/aliases . text 

SEE  ALSO 

elm(l),  newalias(l). 


U  ser  al  i  as  database  data  tabl  e 
User  alias  database  directory  table 
U  ser  al  i  as  database  hash  tabl  e 
U  ser  a  I  i  as  sou  rce  text 
System  alias  database  data  table 
System  alias  database  directory  table 
System  alias  database  hash  table 
System  al  i  as  source  text 
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NAME 

enable,  disable  -  enable/disable  LP  printers 

SYNOPSIS 

enable  printers 

disable  [-c]  [-r[reason ] ]  printers 
DESCRIPTION 

The  enable  command  activates  the  named  printers,  enabling  them  to  print  requests  taken  by  lp.  Use 
lpstat  to  find  the  status  of  printers  (see  lp(l)  and  Ipstat(l)), 

disable  deactivates  the  named  printers,  disabling  them  from  printing  requests  taken  by  lp.  By  default, 
any  requests  that  are  currently  printing  on  the  designated  printers  are  reprinted  in  their  entirety  either  on 
the  same  printer  or  on  another  member  of  the  same  class.  Use  lpstat  to  find  the  status  of  printers. 

Options 

disable  recognizes  the  following  options: 

-c  Cancel  any  requests  that  are  currently  printing  on  any  of  the  designated  printers. 

-r[reason]  Associate  a  reason  with  the  deactivation  of  the  printers.  This  reason  applies  to  all 
printers  mentioned  up  to  the  next  -r  option.  If  the  -r  option  is  not  present  or  the 
-r  option  is  given  without  a  reason,  a  default  reason  is  used,  reason  is  reported  by 
lpstat.  The  maximum  length  of  the  reason  message  is  80  bytes. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LANG  is  not  specified  or  is  null,  it  defaults  to  C  (see  lang(5)). 

If  any  internationalization  variable  contains  an  invalid  setting,  all  internationalization  variables  default  to 
C  (see environ (5)). 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

EXAMPLES 

Enableprinter  snowwhite  to  accept  requests: 

enable  snowwhite 

Deactivate  printer  snowwhite  and  cancel  any  logged  jobs: 
disable  -c  snowwhite 

WARNINGS 

If  the  restrict  cancel  feature  (selected  by  the  lpadmin  -ore  option  —  see  Ipadmin(lM))  is  enabled, 
disable  ignores  the  -c  option. 

enable  and  disable  perform  their  operation  on  the  local  system  only. 

FILES 

/etc/lp/* 
/usr/lib/lp/* 
/ var / adm/ lp/ * 
/var/ spool/lp/* 

SEE  ALSO 

lp(l),  Ipstat(l),  accept(lM),  Ipadmin(lM),  Ipsched(lM),  rcancel(lM),  rlp(lM),  rlpdaemon(lM),  rlpstat(lM). 
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NAME 

env  -  set  environment  for  command  execution 
SYNOPSIS 

env  [-]  [-i]  [name  =  value]  ...    [command  [arguments  ...]] 
DESCRIPTION 

env  obtains  the  current  environment,  modifies  it  according  to  its  arguments,  then  executes  the  command 
with  the  modified  environment.  Arguments  of  the  form  name=value  are  merged  into  the  inherited 
environment  before  the  command  is  executed.  The  -i  option  causes  the  inherited  environment  to  be 
ignored  completely  so  that  the  command  is  executed  with  exactly  the  environment  specified  by  the  argu- 
ments. The  -  option  is  obsolete  and  has  the  same  effect  as  the  -i  option. 

If  no  command  is  specified,  the  resulting  environment  is  printed,  one  name-value  pair  per  line. 
RETURN  VALUE 

If  command  is  invoked,  the  exit  status  of  env  is  the  exit  status  of  command;  otherwise,  env  exits  with 
one  of  the  fol  I  owi  ng  val  ues: 


EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  env  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

WARNING 

The  -  option  is  obsolete.  Use  -i  instead. 

SEE  ALSO 

sh(l),  exec(2),  profile(4),  environ(5). 

STANDARDS  CONFORMANCE 

env:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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env  completed  successfully. 

env  encountered  an  error. 

command  was  found  but  could  not  be  invoked. 

command  could  not  be  found. 
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NAME 

eucset  -  sets  and  gets  code  widths  for  Idterm 

SYNOPSIS 

eucset  [-p] 

eucset  [  [-c  HP15-codeset]  or  [-c  UTF8]  or  [cswidth]  ] 
DESCRIPTION 

The  eucset  command  sets  or  gets  (reports)  the  encoding  and  display  widths  of  the  Extended  UNIX  Code 
(EUC)  and  UCS  Transformation  Format  (UTF8)  characters  processed  by  the  current  input  terminal.  EUC 
is  an  encoding  method  for  codesets  composed  of  single  or  multiple  bytes.  It  permits  applications  and  the 
terminal  hardware  to  use  the  7-bit  US  ASCI  I  code  and  up  to  three  single  byte  or  multi byte  code  sets  simul- 
taneously. 

The  eucset  command  without  any  options,  first  tries  to  set  the  codeset  to  one  of  the  four  HP15  codesets. 
If  unsuccessful,  7-bit  US  ASCI  I  is  used  as  the  default  codeset.  This  command  must  be  used  to  specify  any 
other  EUC  codesets,  whether  they  are  single  byte  or  multibyte.  See  the  WARNINGS  section,  for  special 
warnings  on  the  values  of  the  cswidth  argument. 

To  utilize  this  command  for  UTF8,  specify  UTF8  with  the  -c  option. 
Options 

Theeucset  command  recognizes  the  following  options  and  arguments: 

-p  Displays  the  current  settings  of  the  EUC  character  widths  for  the  terminal. 

-c  Sets  the  codeset  to  one  of  the  four  H  P15  codesets  or  the  UTF8  codeset.  The  H  P15  codesets 

supported  are  SJIS,  CCDC,  GB,  and  BIG5. 

EUC  Code  Set  Classes 

EUC  divides  codesets  into  four  classes.  Each  codeset  has  two  characteristics:  the  number  of  bytes  for 
encoding  the  characters  in  the  codeset,  and  the  number  of  display  columns  to  display  the  characters  in  the 
codeset.  All  characters  within  a  codeset  possess  the  same  characteristics. 

•  Codeset  0  consists  of  all  7-bit,  single  byte  ASCII  characters.  The  most  significant  bit  of  each  of 
these  characters  is  0  (zero).  Characters  in  codeset  0  require  one  byte  for  encoding,  and  occupy  one 
display  column.  These  values  are  fixed  for  codeset  0  (zero).  The  7-bit  US  ASCI  I  code  is  the  pri- 
mary EUC  codeset,  which  is  availableto  users  without  direct  specification. 

•  Codeset  1  is  a  supplementary  EUC  codeset.  Codeset  1  characters  have  an  initial  byte  whose  most 
significant  bit  is  1.  Characters  in  codeset  1  may  require  more  than  one  byte  for  encoding,  and  may 
require  more  than  one  display  column.  The  eucset  command  must  be  used  to  set  the  charac- 
teristics for  codeset  1. 

•  Codesets  2  and  3  are  supplementary  EUC  codesets.  Characters  in  these  codesets  have  an  initial 
byte  of  SS2  or  SS3,  respectively.  They  require  more  than  one  byte  for  encoding,  and  may  require 
more  than  one  display  column.  The  eucset  command  must  be  used  to  set  the  characteristics  for 
codesets  2  and  3. 

The  cswidth  argument  in  the  eucset  command  line  is  a  character  string  that  describes  the  character 
widths  for  codesets  1  through  3.  This  command  does  not  allow  the  user  to  modify  the  settings  for  codeset  0. 
The  character  string  is  of  the  foil  owing  format: 

X1[:Y1],X2[:Y2],X3[:Y3] 

The  value  XI  is  the  number  of  bytes  required  to  encode  a  character  in  codeset  class  1.  Yl  is  the  number  of 
display  columns  needed  to  display  characters  in  this  class.  X2  is  the  number  of  bytes  required  to  encode  a 
character  in  codeset  2,  not  counting  the  SS2  byte,  and  Y2  is  the  number  of  display  columns  for  codeset  2 
characters.  X3  is  the  number  of  bytes  needed  to  encode  characters  in  codeset  3,  not  counting  the  SS3  byte, 
and  Y3  is  the  number  of  display  columns  required  for  these  characters.  The  values  for  the  column  widths 
may  be  omitted  if  they  are  equal  to  the  number  of  encoding  bytes.  If  the  encoding  value  of  any  of  the  EUC 
codesets  is  set  to  0  (zero),  this  indicates  that  the  codeset  does  not  exist.  See  the  WARNINGS  section  for 
special  warnings  on  the  values  of  the  cswidth  argument. 

If  no  cswidth  argument  is  supplied,  the  eucset  command  uses  the  value  of  the  CSWIDTH  environment 
variable.  If  this  variable  is  not  present,  the  foil  owing  default  string  is  substituted: 
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1:1,0:0,0:0 

This  default  string  designates  that  the  environment  uses  a  single  byte  EUC  codeset  that  has  characters  in 
the  EUC  codeset  1  format.  If  the  environment  uses  a  multibyte  EUC  codeset  in  the  codeset  1  format,  sin- 
gle byte  or  multibyte  EUC  codesets  in  the  codeset  2  or  3  format,  or  both,  the  default  setting  cannot  be  used. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  Provide  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If 

LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  C  (see  lang(5))  is  used 
instead  of  LANG.  If  any  of  the  internationalization  variables  contain  an  invalid  set- 
ting, eucset  behaves  as  if  all  internationalization  variables  are  set  to  C.  See 
envi  ron(5). 

LC_ALL  If  set  to  a  nonempty  string  value,  override  the  values  of  all  other  internationalization 

variables. 

LC_ME S SAGE S  Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diag- 
nostic messages  written  to  standard  error  and  informative  messages  written  to  stan- 
dard output. 

NLSPATH  Determines  the  location  of  message  catalogs  for  the  processing  of  LC_ME S SAGE S  . 

EXAMPLES 

To  display  the  encoding  and  display  widths  for  the  EUC  codesets  1  to  3  in  your  environment,  enter: 
eucset  -p 

Assuming  eucset  has  been  previously  used  to  set  for  ja_JP.eucJP,  the  entry  generates  the  following: 

cswidth  2:2,1:1,2:2 

To  change  the  current  settings  of  the  encoding  and  display  widths  for  the  EUC  characters  in  codesets  1  and 
2  to  two  bytes  each,  enter  one  of  the  following: 

eucset  2:2,2:2,0:0 

eucset  2,2,0 

To  set  the  encoding  and  display  widths  for  the  EUC  characters  in  the  locale  ja_JP .  eucJP ,  enter: 

eucset  2:2,1:1,2:2 
For  zh_TW.eucTW,  enter: 

eucset  2:2,3:2 
For  ko_KR .  eucKR ,  enter: 

eucset  2:2 
To  set  thecodewidth  to  that  of  UTF8,  enter: 

eucset  -c  UTF8 
WARNINGS 

The  cswidth  argument  does  not  include  the  SS2  or  SS3  bytes  in  the  byte  width  values. 

This  command  is  not  specified  by  standards,  may  not  be  available  on  other  vendor's  systems,  and  may  be 
subject  to  change  or  obsolescence  in  a  future  release. 

AUTHOR 

eucset  was  developed  by  OSF  and  HP. 

SEE  ALSO 

dtterm(l),  Idterm(l). 
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NAME 

ex,  edit  -  extended  line-oriented  text  editor 
SYNOPSIS 

ex  [-]  [-1]  [-r]  [-R]  [-t  tag]  [-v]  [-wsize]  [-x]  [-C]  [+command]  [file  ...] 

XPG4  Synopsis 

ex  [-rR]  [-s  I  -v]  [-c  command]  [-t  tag]  [-w  size]  [file  ...] 

Obsolescent  Options 

ex  [-rR]  [-|  -v]  [+command]  [-t  tag]  [-w  size]  [file  ...] 

edit  [-]  [-1]  [-r]  [-R]  [-t  tag]  [-v]  [-wsize]  [-x]  [-C]  [+command]  [file  ...] 
Remarks 

The  program  names  ex,  edit,  vi,  view,  and  vedit  are  separate  personalities  of  the  same  program. 
This  manual  entry  describes  the  behavior  of  the  ex/edit  personality.  On  many  HP-UX  and  other  similar 
systems,  e  is  a  synonym  for  ex. 

DESCRIPTION 

The  ex  program  is  the  line-oriented  personality  of  a  text  editor  that  also  supports  screen-oriented  editing 
(see  vi  (1)). 

(XPG4  only.)  Certain  block-mode  terminals  do  not  have  all  the  capabilities  necessary  to  support  the  com- 
plete ex  definition,  such  as  the  full-screen  editing  commands  (visual  mode  or  openmode).  When  these 
commands  cannot  be  supported  on  such  terminals,  this  condition  shall  neither  produce  an  error  message 
such  as  "not  an  editor  command"  nor  report  a  syntax  error. 

The  edit  program  is  identical  to  ex,  except  that  some  editor  option  defaults  are  altered  to  make  the  edi- 
tor somewhat  friendlier  for  beginning  and  casual  users  (see  Editor  Options  below). 

Options  and  Arguments 

ex  recognizes  the  following  command-line  options  and  arguments: 

(Obsolescent)  Suppress  all  interactive-user  feedback.  This  is  useful  when  editor  commands 
are  taken  from  scripts. 

-s  (XPG4only.) 

Suppress  all  interactive-user  feedback.  This  is  useful  when  editor  commands  are  taken 
from  scripts. 

Ignore  the  value  of  the  TERM  and  any  implementation  terminal  type  and  assume  the  ter- 
minal is  a  type  incapableof  supporting  visual  mode. 

Suppress  the  use  of  the  EXINIT  environment  variableand  the  reading  of  the  .exrc  file. 
-1  Set  the  lisp  editor  option  (see  Editor  Options  below). 

-r  Recover  the  specified  files  after  an  editor  or  system  crash.  If  no  file  is  specified,  a  list  of  all 

saved  files  is  printed.  You  must  be  the  owner  of  the  saved  file  in  order  to  recover  it 
(superuser  cannot  recover  files  owned  by  other  users). 

-R  Set  the  readonly  editor  option  to  prevent  overwriting  a  file  inadvertently  (see  Editor 

Options  below). 

-t  tag  (XPG4  only.)  Edit  the  file  containing  the  specified  tag  and  proceed  as  if  the  first  command 

were  :tag  tag.  The  tags  represented  by  the  -t  tag  and  the  ta  command  is  optional.  It 
shall  be  provided  on  any  system  that  also  provides  a  confirming  implementation  of  ctags, 
Otherwise,  the  use  of  the  -t  produces  undefined  results. 

Execute  the  tag  tag  command  to  load  and  position  a  predefined  file.  See  the  tag  com- 
mand in  Command  Descriptions  and  the  tags  editor  option  in  Editor  Options  below. 

-v  I  nvoke  visual  mode  (vi). 

-w  size  Set  the  value  of  the  window  editor  option  to  size  (see  Editor  Options  below).  If  size  is 

omitted,  it  defaults  to  3. 
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-x  Set  encryption  mode.  You  are  prompted  for  a  key  to  initiate  the  creation  or  editing  of  an 

encrypted  file  (see  the  crypt  command  in  Command  Descriptions  below). 

-C  Encryption  option.  Same  as  the  -x  option,  except  that  all  text  read  in  is  assumed  to  have 

been  encrypted. 

-c  command  (XPG4only.) 

+command      (Obsolescent)  Begin  editing  by  executing  the  specified  ex  search  or  positioning  command, 
file  Specify  the  file  or  files  to  be  edited.  If  more  than  one  file  is  specified,  they  are  processed  in 


the  order  given.  If  the -r  option  is  also  specified,  the  files  are  read  from  the  recovery  area. 

(XPG4  only.)  If  both  the  -t  tag  and  -c  command  options  are  given,  the  -t  tag  shall  be  processed  first;i.e, 
the  file  containing  the  tag  is  selected  by  the  -t  and  then  the  command  is  executed. 

Definitions 

Current  file.  The  name  of  the  file  being  edited  by  ex  is  called  the  current  file.  Text  from  the  current  file 
is  read  into  a  work  area,  and  all  editing  changes  are  performed  on  this  work  area.  Changes  do  not  affect 
the  original  file  until  the  work  area  is  explicitly  written  back  to  the  file.  If  the  %  character  is  used  as  a  file 
name,  it  is  replaced  by  the  current  file  name. 

Alternate  file.  The  alternate  file  is  the  name  of  the  last  file  mentioned  in  an  editor  command,  or  the  pre- 
vious current  file  name  if  the  last  file  mentioned  becomes  the  current  file.  If  the  #  character  is  used  as  a 
file  name,  it  is  replaced  by  the  alternate  file  name. 

Buffers.  Twenty-six  buffers  named  a  through  z  can  be  used  for  saving  blocks  of  text  during  the  edit.  If 
the  buffer  name  is  specified  in  uppercase,  text  is  appended  to  the  existing  buffer  contents  rather  than 
overwriting  it. 

Readonly  flag.  The  readonly  flag  can  be  cleared  from  within  the  editor  by  setting  the  noreadonly 

editor  option  (see  Editor  Options  below).  Writing  to  a  different  file  is  allowed  even  when  the  readonly 
flag  is  set.  Also,  a  write  can  be  forced  to  a  readonly  file  by  using  !  after  the  write  command  (see  the 
write  command  in  Command  Descriptions  below). 

Interrupt.  If  an  interrupt  signal  is  received,  and  commands  are  being  supplied  from  a  keyboard,  ex 
returns  to  command  mode.  If  editor  commands  are  coming  from  a  file,  an  interrupt  signal  causes  ex  to 
abort. 

System  crash.  If  the  system  crashes  or  ex  aborts  due  to  an  internal  error  or  unexpected  signal,  ex 
attempts  to  preserve  the  work  area  if  any  unwritten  changes  were  made.  Use  the  -r  command-line  option 
to  retrieve  the  saved  changes. 

Command  mode/input  mode,  ex  starts  up  in  command  mode,  as  indicated  by  the  colon  ( : )  prompt,  ex 
switches  to  input  mode  whenever  an  append,  change,  or  insert  command  is  encountered.  To  ter- 
minateinput  mode  and  return  to  command  mode,  typea  period  (.)  alone  at  the  beginning  of  a  line. 

Comments.  Command  lines  beginning  with  a  quotation  mark  (")  are  ignored  (this  is  useful  for  placing 
comments  in  an  editor  script). 

Multiple  commands  can  be  combined  on  a  single  line  by  separating  them  with  a  vertical  bar  character 
( | ).  However,  global  commands,  comments,  and  the  shell  escape  command  must  be  the  last  command  on  a 
line  because  they  cannot  be  terminated  by  a  |  character. 

Addressing 

(XPG4  only.)  Addressing  in  ex  relates  to  the  current  line.  In  general,  the  current  line  shall  be  the  last  line 
affected  by  the  command;  the  exact  effect  on  the  current  line  is  discussed  under  the  description  of  each 
command.  When  the  buffer  contains  no  lines,  the  current  line  shall  beset  to  zero. 

ex  recognizes  the  following  line  address  forms: 

Dot  or  period  (.)  refers  to  the  current  line.  There  is  always  a  current  line  whose 
position  can  be  the  result  of  an  explicit  movement  command  or  the  result  of  a  com- 
mand that  affects  multiple  lines  (in  which  case  it  is  usually  the  last  line  affected). 

n  The  nth  line  in  the  work  area.  Lines  are  numbered  sequentially,  starting  at  line  1. 

$  The  last  line  in  the  work  area. 

%  Abbreviation  for  1,  $,  meaning  the  entire  work  area. 
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+n,  +[+]...  An  offset  relative  to  the  current  line  or  the  preceding  line  specification.  +  means  for  - 
-n,  -[-]...       ward;  -  means  backward.  For  example,  the  forms  .+3, +3,  and +++ are  equivalent. 

/re/  The  line  containing  the  pattern  re,  scanning  forward  (/)  or  backward  (?).  The  trailing 

?re?  /  or  ?  can  be  omitted  if  the  line  is  only  being  displayed.  If  re  is  omitted,  ex  uses  the 

more  recently  set  of  either  the  scanning  string  or  the  substitution  string  (see  Regular 

Expressions  below). 

'  x  Lines  can  be  marked  using  single  lowercase  letters  (see  the  mark  command  in  Com- 

mand Descriptions  below).  '  x  refers  to  the  line  marked  with  x.  I  n  addition,  the  pre- 
vious current  line  is  marked  before  each  nonrelative  motion.  This  line  can  be  referred 
to  by  using  '  for  x  (thus  '  '  refers  to  the  previous  current  line). 

(XPG4only.)  Commands  require  zero,  one  or  two  addresses.  Commands  that  require 
zero  addresses  shall  regard  the  presence  of  an  address  as  an  error. 

(XPG4  only.)  Adjacent  address  in  a  range  shall  be  separated  from  each  other  by  a  comma  (,)  or  a  semi- 
colon(;).  In  the  latter  case,  the  current  line(.)  shall  beset  to  the  first  address,  and  only  then  is  the  second 
address  calculated.  This  feature  can  be  ued  to  determine  the  starting  line  for  forwards  and  backwards 
searches.  The  second  address  of  any  two-address  sequence  shall  correspond  to  the  first  address.  The  first 
address  shall  be  less  than  or  equal  to  the  second  address.  The  first  address  shall  be  greater  than  or  equal  to 
the  first  line  of  the  editing  buffer,  and  the  last  address  shall  be  less  than  or  equal  to  the  last  line  of  the  edit- 
i  ng  buffer.  Any  other  case  shal  I  be  an  error. 

Addresses  for  commands  consist  of  a  series  of  line  addresses  (specified  as  above),  separated  by  a  comma  (, ) 
or  semicolon  (;).  Such  address  lists  are  evaluated  left-to-right.  When  the  separator  is  a  semicolon,  the 
current  line  is  set  to  the  value  of  the  previous  address  before  the  next  address  is  interpreted.  If  more 
addresses  are  given  than  the  command  requires,  then  all  but  the  last  one  or  two  are  ignored.  Where  a  com- 
mand requires  two  addresses,  the  first  line  addressed  must  precede  the  second  one  in  the  work  area.  A 
null  (missing)  address  in  a  list  defaults  to  the  current  line. 


Regular  Expression 

The  editor  maintains  copies  of  two  regular  expression  strings  at  all  times:  the  substitution  string,  and  the 
scanning  string.  The  substitute  command  sets  the  substitution  string  to  the  regular  expression  used.  Both 
the  global -command  and  the  regular-expression  form  of  line  addressing  (see  Addressing  above)  for  all  com- 
mands set  the  scanning  string  to  the  regular  expression  used.  These  strings  are  used  as  default  regular 
expressions  as  described  under  Addressing,  the  global  command,  and  the  substitute  command. 

The  editor  supports  Basic  Regular  Expressions  (see  regexp(5))  with  the  foil  owing  modifications: 

\<  The  \<  matches  the  beginning  of  a  "word";  that  is,  the  matched  string  must  begin  in  a 

letter,  digit,  or  underline,  and  must  be  preceded  by  the  beginning  of  the  line  or  a  charac- 
ter other  than  the  above.  This  construct  can  only  be  used  at  the  beginning  of  a  regular 
expression  (as  in  \  -sword),  but  not  in  the  middle  (wordl  \  <word2). 

\>  The  \>  matches  the  end  of  a  "word"  (see  previous  paragraph).  This  construct  can  only  be 

used  at  the  end  of  a  regular  expression  (as  in  word\  >),  but  not  in  the  middle  (wordl\  > 
word2). 

Match  the  replacement  part  of  the  last  substitute  command. 

[string]  The  positional  quoting  within  bracket  expressions  defined  by  Basic  Regular  Expressions 
is  replaced  by  the  use  of  the  backslash  (\)  to  quote  bracket-expression  special  characters. 

nomagic  When  the  editor  option  nomagic  is  set,  the  only  characters  with  special  meanings  are  " 
at  the  beginning  of  a  pattern,  $  at  the  end  of  a  pattern,  and  \ .  The  characters  .,  *,  [, 
and  ~  lose  their  special  meanings  unless  escaped  by  a  \. 


Replacement  Strings 

The  character  &  in  the  replacement  string  stands  for  the  text  matched  by  the  pattern  to  be  replaced.  Use 
\&  if  the  nomagic  editor  option  is  set. 

The  character  ~  is  replaced  by  the  replacement  part  of  the  previous  substitute  command.  Use  \~  if 
the  nomagic  editor  option  is  set. 

The  sequence  \n,  where  n  is  an  integer,  is  replaced  by  the  text  matched  by  the  subpattern  enclosed  in  the 
nth  set  of  parentheses  \  (  and  \) . 
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The  sequence  \u  (\1)  causes  the  immediately  following  character  in  the  replacement  to  be  converted  to 
uppercase  (lowercase),  if  the  character  is  a  letter.  The  sequence  \U  (\L)  turns  case  conversion  on,  until  the 
sequence  \E  or  \e  is  encountered,  or  the  end  of  the  replacement  string  is  reached. 

Command  Names  and  Abbreviations 

The  following  table  summarizes  the  line-mode  commands.  The  commands  whose  names  are  enclosed  in 
parentheses  are  availableonly  in  their  abbreviated  forms. 


Command 

Abbr. 

Command 

Abbr. 

Command 

Abbr. 

abbreviate 

ab 

next 

n 

tag 

ta 

append 

a 

number 

nu  # 

unabbr evi  at  e 

una 

args 

ar 

open 

o 

undo 

u 

change 

c 

pop 

unmap 

unm 

chdir 

chd  cd 

preserve 

pre 

version 

ve 

copy 

CO  t 

print 

P 

visual 

vi 

crypt 

cr  X 

put 

pu 

write 

w  wq 

delete 

d 

quit 

q 

xit 

X 

edit 

e  ex 

read 

r 

yank 

ya 

file 

f 

recover 

rec 

global 

g  v 

rewind 

rew 

(execute  buffer) 

*  @ 

insert 

i 

set 

se 

(line  number) 

join 

j 

shell 

sh 

(left  shift) 

< 

list 

1 

source 

so 

(right  shift) 

> 

map 

stop 

St  "Z 

(scroll) 

AD 

mark 

ma  k 

substitute 

s  sr  & 

(shell  escape) 

! 

move 

m 

suspend 

su  "Z 

(wi  ndow) 

z 

Command  Descriptions 

I  n  the  foil  owing  command  descriptions,  some  arguments  appear  frequently.  They  are  described  below. 

line  A  single  line  address,  in  any  of  the  forms  described  in  Addressing  above.  The  default  is  the 
current  line. 

range  A  pair  of  line  addresses  separated  by  a  comma  or  semicolon,  as  described  in  Addressing 
above.  Thedefault  isthecurrent  I ine ( . ,  . ). 

count  A  positive  integer  specifying  the  number  of  lines  to  be  affected  by  the  command.  The 
default  is  1  or  the  number  of  lines  in  range. 

When  count  is  specified,  range  is  ineffective.  Instead,  only  a  line  number  should  be 
specified  to  indicate  the  first  line  affected  by  the  command.  (If  a  range  is  given,  the  last 
I  ine  of  the  range  is  interpreted  as  the  starting  I  ine  for  the  command.) 

flags  One  or  more  of  the  characters  #,  p,  and  1.  The  corresponding  command  to  print  the  line  is 
executed  after  the  command  completes.  Any  number  of  +  or  -  characters  can  also  be  given 
with  these  flags.  Thedefault  is  no  flags. 

These  modifiers  are  all  optional. 

When  only  a  lineor  a  range  is  specified  (with  a  null  command),  the  implied  command  is  print.  If  a  null 
line  is  entered,  the  next  line  is  printed  (equivalent  to  .  +lp) 

buffer  XPG4  Feature.  One  of  a  number  of  named  areas  for  saving  text.  The  named  buffers  are 
specified  by  the  lowercase  letters  of  the  POSIX  locale.  Specifying  buffer  shall  cause  the 
area  of  the  text  affected  by  the  command  to  be  stored  into  the  buffer  as  it  was  before  the 
command  took  effect.  This  argument  is  also  used  on  the  put  command  and  the  visual 
mode  "put"  commands  (p  and  P),  to  specify  the  buffer  that  shall  provide  the  text  to  insert. 

If  the  buffer  name  is  specified  in  uppercase,  and  the  buffer  is  to  be  modified,  the  buffer  shall 
be  appended  to  rather  than  being  overwritten.  If  the  buffer  is  not  to  be  modified,  the  buffer 
name  can  be  specified  in  lowercase  or  uppercase  with  the  same  results.  There  shall  be  also 
one  unnamed  buffer,  which  is  the  repository  for  all  text  deleteed  or  yanked  when  no  buffer 
is  specified. 
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There  are  also  numbered  buffers,  1  through  9,  which  shall  be  accessible  only  from  visual 
mode.  These  buffers  are  special  in  that,  in  the  visual  mode,  when  deleted  text  is  placed  in 
the  unnamed  buffer,  it  also  shall  be  placed  in  buffer  1,  the  previous  contents  buffer  1  shall 
be  placed  in  buffer  2  and  so  on.  Any  text  in  the  buffer  9  shall  be  lost.  Text  that  is  yanked 
into  the  unnamed  buffer  shall  not  modify  the  numbered  buffers.  Text  cannot  be  placed 
directly  into  the  numbered  buffered,  although  it  can  be  retrieved  from  them  by  using  a 
visual  mode  "put"  command  with  the  buffer  name  given  as  s  number.  When  the  buffer 
modifier  is  not  used  in  the  commands  below,  the  unnamed  buffer  shall  be  the  default. 

word  XPG4  Feature.  In  the  POSIX  Locale,  a  word  consists  of  a  maximal  sequence  of  letters, 
digits  and  underscores,  delimited  at  both  ends  by  characters  other  than  letters,  digits,  or 
underscores,  or  by  the  beginning  or  end  of  a  word  or  the  file.  !  A  character  that  can  be 
appended  to  the  command  to  modify  its  operation,  as  detailed  in  the  individual  command 
descriptions. 

If  both  a  count  and  range  is  specified  for  a  command  that  uses  them,  the  number  of 
lines  affected  shall  be  taken  from  the  count  value  rather  than  the  range.  The  starting 
line  for  the  command  shall  betaken  to  be  the  first  line  addressed  by  the  range. 

When  only  a  line  or  range  is  specified  with  no  command,  the  implied  command  shall  be 
either  print,  list,  or  number  (  p,  1,  or  #).  The  command  selected  shall  be  the  last  of 
these  three  commands  to  be  used.  When  no  range  or  count  is  specified  and  the  command 
line  is  a  blank  line,  the  current  line  shall  be  written,  and  the  current  line  shall  be  set  to 
.+1. 

Zero  or  mode  <blank> characters  can  precede  or  follow  the  addresses,  count  or  command 
name.  Any  object  following  a  command  name  (such  as  buffer,  file  etc)  that  begins  with  an 
alphabetic  character  shall  be  separated  from  the  command  name  with  at  least  one  <blank>. 

For  each  of  the  commands  listed  below,  the  command  can  be  entered  as  the  abbreviation  (those  characters 
in  the  Synopsis  command  word  preceding  the  [),  the  full  command  (all  characters  shown  for  the  command 
word,  omitting  the  [  and  ]),  or  any  subset  of  the  characters  of  the  full  command  down  to  the  abbreviation. 

abbreviate      abbreviate ]  word  replacement 

Add  the  named  abbreviation  to  the  current  list.  In  visual  mode,  if  word  is  typed  as  a 
complete  word  during  input,  it  is  replaced  by  the  string  replacement. 

append  linea[ppend][ !  ] 

Enter  input  mode;  the  input  text  is  placed  after  the  specified  line.  If  line  0  is  specified, 
the  text  is  placed  at  the  beginning  of  the  work  area.  The  last  input  line  becomes  the 
current  line,  or  the  target  line  if  no  lines  are  input. 

Appending  !  to  the  command  toggles  the  autoindent  editor  option  setting  for  this 
insert  only. 

args  ar[gs] 

Prints  the  argument,  placing  the  current  argument  between  [  and  ] . 

change  range  c[hange][ !  ]  count 

Enter  input  mode;  the  input  text  replaces  the  specified  lines.  The  last  input  line 
becomes  the  current  line;  if  no  lines  are  input,  the  effect  is  the  same  as  a  delete. 

Appending  !  to  the  command  toggles  the  autoindent  editor  option  setting  for  this 
insert  only. 

chdir  chd[ir][!]  [directory] 

cd[!]  [  directory] 

Change  the  working  directory  to  directory.  If  directory  is  omitted,  the  value  of  the 
HOME  environment  variable  is  used.  If  the  work  area  has  been  modified  si  nee  the  last 
write  and  the  name  of  the  file  being  edited  does  not  begin  with  a  slash  (/),  a  warning  is 
issued  and  the  working  directory  is  not  changed.  To  force  a  change  of  directory  in  this 
case,  append  the  character  !  to  the  command. 

copy  range co[py]  line  flags 

range  t  lineflags 
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A  copy  of  the  specified  lines  (range)  is  placed  after  the  specified  destination  line;  line  0 
specifies  that  the  lines  are  to  be  placed  at  the  beginning  of  the  work  area.  (The  letter  t 
is  an  alternative  abbreviation  for  the  copy  command.) 

cr[ypt] 
X 

The  user  is  prompted  for  a  key  with  which  to  enter  encryption  mode.  This  command 
can  also  be  used  to  change  the  key  entered  from  a  previous  crypt  command  or  the  -x 
command  line  option.  If  no  key  is  supplied  in  response  to  the  prompt  (that  is,  only  car- 
riage return  is  pressed),  encryption  mode  is  canceled  and  the  work  area  is  written  out  in 
plain-text  form  by  subsequent  write  commands. 

While  in  encryption  mode,  all  file  input  is  decrypted  using  the  current  key.  However, 
while  an  input  file  is  being  processed,  if  a  block  of  text  (approximately  1024  bytes)  is 
encountered  that  contains  only  7-bit  ASCI  I  characters,  that  block  of  text  is  assumed  to 
be  plain-text  and  is  not  decrypted.  All  file  output,  except  that  piped  via  a  !  shell  escape 
to  another  command,  is  encrypted  using  the  current  key. 

The  temporary  file  used  by  the  editor  to  manage  the  work  area  is  not  encrypted  until 
the  current  work  area  is  discarded  (or  written  out)  and  editing  begins  on  a  new  file. 
When  creatinga  newfilethat  requires  encryption  protection,  ensure  that  the  work  area 
file  is  also  encrypted  by  specifying  the  -x  option  when  invoking  the  editor. 

cr[ypt] 
C 

Encryption  option.  Same  as  the  X  command,  except  that  all  text  read  in  is  assumed  to 
have  been  encrypted. 

range  d[elete]  buffer  count 

The  specified  lines  are  deleted  from  the  work  area.  If  a  named  buffer  is  specified,  the 
deleted  text  is  saved  in  it.  If  no  buffer  is  specified,  the  unnamed  buffer  is  used  (that  is, 
the  buffer  where  the  most  recently  deleted  or  yanked  text  is  placed  by  default).  The 
new  current  line  is  the  line  after  the  deleted  lines  or  the  last  line  of  the  file  if  the  deleted 
lines  were  at  the  end  of  the  file. 

e[dit][!]  [+  line]  file 
ex[!]  [+  line]  file 

Begin  editing  a  new  file  (ex  is  an  alternative  name  for  the  edit  command).  If  the 
current  work  area  has  been  modified  since  the  last  write,  a  warning  is  printed  and  the 
command  is  aborted.  This  action  can  be  overridden  by  appending  the  character  !  to  the 
command  (e!  file).  The  current  line  is  the  last  line  of  the  work  area  unless  it  is  exe- 
cuted from  within  vi ,  in  which  case  the  current  line  is  the  first  line  of  the  work  area.  If 
the  +line  option  is  specified,  the  current  line  is  set  to  the  specified  position,  where  line 
can  be  a  number  (or  $)  or  specified  as  /re  or  ?re. 

f[ile] 

Print  the  current  file  name  and  other  information,  including  the  number  of  lines  and  the 
current  position. 

rangeg[lobal][!]  /re/ command... 
range v  /re/  command... 

Perform  command  on  lines  within  range  (or  on  the  entire  work  area  if  no  range  is  given) 
that  contain  re.  First  mark  the  lines  within  the  given  range  that  match  the  pattern  re. 
If  the  pattern  is  omitted,  the  more  recently  set  of  either  the  substitution  string  or  the 
scanning  string  is  used  (see  Regular  Expressions  above).  Then  the  given  commands  are 
executed  with  .  set  to  each  marked  line.  Any  character  other  than  a  letter  or  a  digit 
can  be  used  to  delimit  the  pattern  instead  of  the  /. 

command  can  be  specified  on  multiple  lines  by  hiding  new-lines  with  a  backslash.  If 
command  is  omitted,  each  line  is  printed,  append,  change,  and  insert  commands 
are  allowed;  the  terminating  dot  can  be  omitted  if  it  ends  command  or  commands.  The 
visual  command  is  also  permitted  (unless  the  global  command  itself  has  been 
issued  from  visual  mode),  and  takes  input  from  the  terminal.  (If  command  contains  a 
visual-mode  command  (that  is,  open  or  visual),  the  visual-mode  command  must  be 
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terminated  by  the  visual-modeQ  command  in  order  to  proceed  to  the  next  marked  line.) 

The  global  command  itself  and  the  undo  command  are  not  allowed  in  command. 
The  editor  options  autoprint ,  autoindent,  and  report  are  inhibited. 

Appendinga  !  to  the  global  command  (that  is,  g!  ...)  or  using  the  alternate  name  v 
causes  command  to  be  run  on  the  lines  within  range  that  do  not  match  the  pattern. 

Iinei[nsert][!] 

Enter  input  mode;  the  input  text  is  placed  before  the  specified  line.  The  last  line  input 
becomes  the  current  line,  or  the  line  before  the  target  line,  if  no  lines  are  input. 

Appending  !  to  the  command  toggles  the  autoindent  editor  option  setting  for  this 
insert  only. 

range  j[oin][!]  count  flags 

J  oin  together  the  text  from  the  specified  lines  into  one  line.  White  space  is  adjusted  to 
provide  at  least  one  blank  character  (two  if  a  period  appears  at  the  end  of  a  line,  or  none 
if  the  first  character  of  a  line  is  a  closing  parenthesis  () )).  Extra  white  space  at  the 
beginning  of  a  line  is  discarded. 

Appendinga  !  to  the  command  causesa  simpler  join  with  no  white-space  processing, 
range l[ist]  ount  flags 

Print  the  specified  lines  with  tabs  displayed  as  "I  and  the  end  of  each  line  marked  with 
a  trailing  $.  (The  only  useful  flag  is  #  for  line  numbers.)  The  last  line  printed  becomes 
the  current  line. 

map  key  |  #n  action 


map!  key  |  #n  action 

The  map  and  map!  commands  define  macros  for  use  in  visual  mode.  The  first  argu- 
ment, key,  can  be  a  single  character  or  a  multicharacter  sequence.  In  the  special 
sequence,  #n,  n  is  a  digit  referring  to  the  function  key  n.  Special  characters,  whi- 
tespace,  and  newline  must  be  escaped  with  a  "V  to  be  entered  in  the  arguments.  The 
key  argument  cannot  contain  a  colon  ( : )  as  its  first  character,  nor  can  a  multicharacter 
sequence  begi  n  with  an  alphabetic  character. 

Macros  defined  by  map  are  effective  in  visual  command  mode.  Macros  defined  by  map! 
are  effective  in  visual  input  mode.  When  key  or  the  function  key  corresponding  to  #n  is 
entered,  the  editor  interprets  the  operation  as  though  action  were  typed. 

The  map  or  map!  command  without  options  displays  the  corresponding  current  list  of 
macros. 

See  also  the  editor  options  keyboardedit ,  keyboardedit ! ,  timeout,  and 
timeoutlen  in  Editor  Options  below. 

Iinema[rk]  x 
line  k  x 

The  specified  line  is  given  the  specified  mark  x,  which  must  be  a  single  lowercase  letter 
(a-z).  x  must  be  preceded  by  a  space  or  tab.  Thecurrent  lineposition  is  not  affected,  k 
is  an  alternate  name  for  mark. 

range m[ove]  line 

Move  the  specified  lines  (range)  to  follow  the  target  line.  The  first  line  moved  becomes 
the  current  line. 

n[ext][!]  [file  ...] 

The  next  filefrom  the  command  lineargument  list  is  edited.  Appendinga  !  to  the  com- 
mand overrides  the  warning  about  the  work  area  having  been  modified  since  the  last 
write  (and  discards  any  changes  unless  the  autowrite  editor  option  is  set).  The  argu- 
ment list  can  be  replaced  by  specifying  a  new  one  on  this  command  line. 

rangenu[mber]  count  flags 
range  #  count  flags 
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(The  #  character  is  an  alternative  abbreviation  for  the  number  command.)  Print  the 
lines,  each  preceded  by  its  line  number  (the  only  useful  flag  is  1).  The  last  line  printed 
becomes  the  current  line. 

lineo[pen]  /re/  flags 

Enter  open  mode,  which  is  similar  to  visual  mode  with  a  one-line  window.  All  the 
visual-mode  commands  are  available.  If  a  match  isfound  in  I  inefor  the  optional  regular 
expression,  the  cursor  is  placed  at  the  start  of  the  matching  pattern.  Use  the  visual 
mode  command  Q  to  exit  from  open  mode.  For  more  information,  seevi(l). 

pop[ !  ] 

Load  the  file  whose  name  is  stored  at  the  top  of  the  tag  stack  and  set  the  current  line  to 
the  stored  location.  The  top  entry  of  the  tag  stack  is  deleted.  (The  current  file  name  is 
placed  on  the  stack  when  you  execute  the  line  mode  tag  command  or  the  visual  mode 
A]  command.) 

!  overrides  the  warning  about  the  work  area  having  been  modified  si  nee  the  last  write; 
any  changes  are  discarded  unless  the  autowrite  editor  option  is  set). 

pre  [serve] 

The  current  editor  work  area  is  saved  as  if  the  system  had  just  crashed.  Use  this  com- 
mand in  emergencies,  for  example  when  a  write  does  not  work  and  the  work  area  can- 
not be  saved  in  any  other  way.  Use  the  -r  command-line  option  to  recover  the  file. 
After  the  file  has  been  preserved,  a  mail  message  shall  be  sent  to  the  user.  The  message 
shall  contain  the  name  of  the  file,  the  time  of  preservation  and  an  ex  command  that 
could  be  used  to  recover  the  file.  Additional  information  may  be  included  in  the  mail 
message. 

range  p[rint]  count 

Print  the  specified  lines,  with  non-printing  characters  printed  as  control  characters  in 
the  form  ~x;  DEL  is  represented  as  "?.  Thelast  line  printed  becomes  the  current  line. 

Iinepu[t]  buffer 

Place  deleted  or  "yanked"  lines  after  line.  A  buffer  can  be  specified;  otherwise,  the  text 
in  the  unnamed  buffer  (that  is,  the  buffer  in  which  deleted  or  yanked  text  is  placed  by 
default)  is  restored.  The  current  line  indicator  shall  beset  to  the  first  line  put  back. 

q[uit][!] 

Terminate  the  edit.  If  the  work  area  has  been  modified  since  the  last  write,  a  warning 
is  printed  and  the  command  fails.  To  force  termination  without  preserving  changes, 
append  !  to  the  command. 

Iiner[ead]  file 

Placea  copy  of  the  specified  filein  the  work  area  after  the  target  line(which  can  beline 
0  to  place  text  at  the  beginning).  If  no  file  is  named,  the  current  file  is  the  default.  If  no 
current  file  exists,  file  becomes  the  current  file.  The  last  line  read  becomes  the  current 
line  except  in  visual  mode  where  the  first  line  read  becomes  the  current  line. 

If  file  is  given  as  ! string,  string  is  interpreted  as  a  system  command  and  passed  to 
the  command  interpreter;  the  resultant  output  is  read  into  the  work  area.  A  blank  or 
tab  must  precede  the  ! . 

rec[over][!]  file 

Recover  file  from  the  save  area,  after  an  accidental  hangup  or  a  system  crash.  If  the 
current  work  area  has  been  modified  since  the  last  write,  a  warning  is  printed  and  the 
command  is  aborted.  This  action  can  be  overridden  by  appending  the  character  !  to  the 
command  (rec!  file). 

rew[ind][ !  ] 

The  argument  list  is  rewound,  and  the  first  file  in  the  list  is  edited.  This  shall  be 
equivalent  to  a  next  command  with  the  current  argument  list  as  its  operands.  If  the 
current  buffer  has  been  modified  si  nee  the  last  write,  a  warning  shall  be  written  and  the 
command  shall  be  aborted.  Any  warnings  can  be  overridden  by  appending  a  !.  The 
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current  indicator  line  shall  be  affected  by  the  editor  options,  autowrite  and  wri- 
teany. 

set  sett]  [all] 

se[t]  [no]boolean-option? 
se[t]  value-option[?] 
se[t]  boolean-option 
se[t]  noboolean-option 
se[t]  value-option=value 

Set  and  display  the  values  of  the  editor  options  (see  Editor  Options  below). 

With  no  arguments,  the  command  prints  those  editor  options  whose  values  have  been 
changed  from  the  default  settings.  If  all  is  specified,  it  prints  all  current  option 
values. 

The  second  and  third  forms  display  the  current  value  of  the  specified  option.  The  ?  is 
necessary  only  for  Boolean  options. 

Thefourth  form  turns  a  Boolean  option  on.  Thefifth  form  turns  a  Boolean  option  off. 

The  sixth  form  assigns  values  to  string  and  numeric  options.  Spaces  and  tabs  in  strings 
must  be  escaped  with  a  leading  backslash  (\). 

The  last  five  forms  can  be  combined;  interpretation  is  left-to-right. 

shell  sh[ell] 

Execute  the  command  interpreter  specified  by  the  shell  editor  option  (see  Editor 
Options  below).  Editing  is  resumed  when  you  exit  from  the  command  interpreter. 

source  so[urce]file 

Read  and  execute  commands  from  the  specified  file,  so  commands  can  be  nested.  The 
maximum  supported  nesting  depths  is  implementation  defined,  but  shall  beat  least  one. 

substitute      range  substitute  ]  /re/repl/  options  count  flags 
range  s  options  count  flags 
range  &  options  count  flags 
range  sr  options  count  flags 
range  ~  options  count  flags 
range  s\?repl 
range  s\&repl 

On  each  specified  line,  the  first  instance  of  the  pattern  re  is  replaced  by  the  string  repl . 
(See  Regular  Expressions  and  Replacement  Strings  above.)  Any  character  other  than  a 
letter  or  a  digit  can  be  used  to  delimit  the  pattern  instead  of  the  /. 

If  you  include  the  g  (global)  option,  all  instances  of  the  pattern  in  the  line  are  substi- 
tuted. 

If  you  include  the  c  (confirm)  option,  you  are  queried  about  whether  to  perform  each 
individual  substitution,  as  follows:  Before  each  substitution  the  line  is  displayed  with 
the  pattern  to  be  replaced  marked  underneath  with  carets  (").  Typey  to  cause  the  sub- 
stitution to  be  performed;  any  other  input  to  abort  it.  The  last  line  substituted  becomes 
the  current  line. 

If  the  substitution  pattern  re  is  omitted  (s//repl/),  the  more  recently  set  of  either  the 
substitution  string  or  the  scanning  string  is  used  (see  Regular  Expressions  above). 

If  the  s  or  &  forms  of  the  command  are  used,  the  substitution  pattern  defaults  to  the 
previous  substitution  string  and  the  replacement  string  defaults  to  the  previous  replace- 
ment string  used. 

If  the  sr  or  ~  forms  of  the  command  are  used,  the  substitution  pattern  defaults  to  the 
more  recently  set  of  either  the  substitution  string  or  the  scanning  string  and  the 
replacement  string  defaults  to  the  previous  replacement  string  used. 

Theform  s\?repl  is  equivalent  to  s/scan-re/repl  /,  where  scan-re  is  the  previous  scan- 
ning string. 
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The  form  s\&repl  is  equivalent  to  s/subs-re/repl /,  where  subs-re  is  the  previous  sub- 
stitution string. 

suspend  su[spend][ !  ] 

stop  st[op][!] 

susp 

Suspend  the  editor  job  and  return  to  the  calling  shell,  stop  and  susp  are  equivalent  to 
suspend,  susp  is  the  user  process  control  suspend  character,  which  is  typically  the 
character  "Z  (ASCII  SUB)  (see  stty(l)).  This  command  is  disabled  if  the  calling  shell 
does  not  support  job  control  or  has  disabled  it. 

The  work  area  is  written  to  the  current  file  before  the  editor  is  suspended  if  the 
autowrite  editor  option  is  set,  the  readonly  editor  option  is  not  set,  and  the  work 
area  has  been  modified  si  nee  the  last  write.  To  override  this  action,  append  the  !  char- 
acter to  the  suspend  or  stop  command. 

tag  ta[g][!]  tag 

Search  the  files  specified  by  the  tags  editor  option  (see  Editor  Options  below)  sequen- 
tially until  a  tag  definition  for  tag  is  found.  If  tag  is  found,  load  the  associated  file  into 
the  work  area  and  set  the  current  position  to  the  address  specified  in  the  tag  definition. 

The  work  area  is  written  to  the  current  file  before  the  new  file  is  loaded  if  the  new  file  is 
different  from  the  current  file,  the  autowrite  editor  option  is  set,  the  readonly 
editor  option  is  not  set,  and  the  work  area  has  been  modified  since  the  last  write.  To 
override  this  action,  append  the  !  character  to  the  command. 

If  the  tagstack  editor  option  is  set,  the  current  file  name  and  line  number  is  pushed 
onto  the  tag  stack  for  later  recall  with  the  line  mode  pop  command  or  the  visual  mode 
A]  command. 

unabbreviate  una[bbreviate  ]  word 

Delete  word  from  the  list  of  abbreviations  (see  the  abbreviate  command  above). 


undo 


unmap 


version 


visual 


write 


u[ndo] 

Reverse  the  changes  made  by  the  previous  editing  command.  For  this  purpose,  glo- 
bal and  visual  are  considered  single  commands.  Commands  that  affect  the  external 
environment,  such  as  write,  edit,  and  next,  cannot  be  undone.  An  undo  can  itself 
be  reversed. 

unm[ap][!]  key 

The  macro  definition  for  key  is  removed  (see  the  map  command  above). 
ve[rsion] 

Print  the  current  version  information  for  the  editor. 

Iinevi[sual]  type  count  flags 

Enter  visual  mode  at  the  specified  line. 

The  type  can  be  one  of  the  characters  +,  -,  . ,  or  ",  as  in  the  z  (window)  command,  to 
specify  the  position  of  the  specified  line  on  the  screen  window  The  default  is  to  pi  ace  the 
I  i  ne  at  the  top  of  the  screen  wi  ndow. 

A  count  specifies  an  initial  window  size;  the  default  is  the  value  of  the  editor  option 
window . 

The  flags  #  and  1  (ell)  cause  the  lines  in  the  visual  window  to  be  displayed  in  the 
corresponding  mode  (see  the  number  and  list  commands). 

Use  the  Q  command  to  exit  visual  mode.  For  more  information,  see  vi  (1). 

[range]  w[rite][ !  ][»]  file 
[range]  wq[ !  ][»]  file 

Write  the  specified  lines  (or  the  entire  work  area,  if  no  range  is  given)  out  to  file,  print- 
ing the  number  of  lines  and  characters  written.  If  file  is  not  specified,  the  default  is  the 
current  file  (the  command  fails  with  an  error  message  if  there  is  no  current  file  and  no 
file  is  specified). 
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If  an  alternate  file  is  specified  and  the  file  exists,  the  write  fails,  but  can  be  forced  by 
appending  !  to  the  command.  To  append  to  an  existing  file,  append  »  to  the  com- 
mand. If  thefiledoes  not  exist,  an  error  isreported. 

If  the  file  is  specified  as  !  string,  string  is  interpreted  as  a  system  command,  the  com- 
mand interpreter  is  invoked,  and  the  specified  lines  are  passed  as  standard  input  to  the 
command. 

The  command  wq  is  equivalent  to  a  w  followed  by  a  q.  wq!  is  equivalent  to  w!  followed 
byq.  wq»  is  equivalent  to  w»  followed  by  q. 

x[it][!][»]file 

If  changes  have  been  made  to  the  work  area,  a  write  command  is  executed  with  any 
options  (such  as  !,  »,  or  file)  used  by  the  write  command.  Then  (in  any  case)  the 
quit  command  is  executed. 

range ya[nk]  buffer  count 

Place  the  specified  lines  in  the  named  buffer.  If  no  buffer  is  specified,  the  unnamed 
buffer  is  used  (that  is,  the  buffer  where  the  most  recently  deleted  or  yanked  text  is 
placed  by  default). 

*  [buffer] 
@  [buffer] 

Execute  the  contents  of  buffer  as  an  editor  command,  buffer  can  be  the  letter  of  a 
named  buffer  (a-z)  or  *  or  @.  The  *  and  the  @  forms  of  this  command  are  equivalent. 
If  a  buffer  is  not  specified  or  buffer  is  *  or  @,  the  buffer  last  named  in  a  *  or  @  command 
is  executed. 

I  i  ne  =  flags 

Print  the  line  number  of  the  specified  line.  The  default  is  the  last  line.  The  current  line 
position  is  not  affected. 

AD 

Print  the  next  n  lines,  where  n  is  the  value  of  the  scroll  editor  option. 

!  command 
range  !  command 

Pass  the  remainder  of  the  line  after  the  !  to  the  system  command  interpreter  for  execu- 
tion. A  warning  is  issued  if  the  work  area  has  been  changed  since  the  last  write.  A  sin- 
gle !  is  printed  when  the  command  completes.  Thecurrent  lineposition  is  not  affected. 

Within  the  text  of  command,  %  and  #  are  expanded  as  file  names,  and  !  is  replaced 
with  the  text  of  the  previous  !  command.  Thus,  !  !  repeats  the  previous  !  command. 
When  such  expansion  is  performed,  the  expanded  line  is  echoed. 

If  you  specify  range,  the  specified  lines  are  passed  to  the  command  interpreter  as  stan- 
dard input.  The  output  from  the  command  replaces  the  specified  lines. 

range  <  count  flags 

Shift  the  specified  lines  to  the  left.  The  number  of  spaces  to  be  deleted  is  determined  by 
the  editor  option  shiftwidth.  Only  whitespace  (blanks  and  tabs)  is  lost  in  shifting; 
other  characters  are  not  affected.  The  last  line  changed  becomes  the  current  line. 

range  >  count  flags 

Shift  the  specified  lines  to  the  right  by  inserting  whitespace  The  number  of  spaces 
inserted  is  determined  by  the  editor  option  shiftwidth.  The  last  line  changed 
becomes  the  current  line. 

line  z  type  count  flags 

The  number  of  lines  specified  by  count  are  displayed.  The  default  for  count  is  the  value 
of  the  editor  option  window. 

If  type  is  omitted,  count  lines  foil  owing  the  specified  lineare  printed. 
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If  type  is  specified,  it  must  be  one  of  the  foil  owing  characters: 

+     Display  a  window  of  lines  foil  owing  the  addressed  line. 

PI  ace  the  addressed  line  at  the  bottom  of  the  window  of  displayed  lines. 

PI  ace  the  addressed  line  at  the  center  of  the  window. 
A     Display  a  window  of  lines  that  is  two  windows  prior  to  the  addressed  line. 
=     Display  the  addressed  line  at  the  center  of  the  window  with  a  line  of  dashes  above 

and  below  the  addressed  line. 

The  last  line  printed  becomes  the  current  line,  except  for  the  =,  where  the  addressed 
line  becomes  the  current  line. 

Editor  Options 

The  command  ex  has  a  number  of  options  that  modify  its  behavior.  These  options  have  default  settings, 
which  can  be  changed  using  the  set  command  (see  above).  Options  can  also  be  set  at  startup  by  putting  a 
set  command  string  in  the  environment  variableEXlNlT,  or  in  the  file  .  exrc  in  the  HOME  directory,  or 
in  .exrc  in  the  current  directory.  If  EXINIT  exists,  the  .exrc  file  in  the  HOME  directory  is  not  exe- 
cuted. If  the  current  directory  is  not  the  HOME  directory  and  the  exrc  editor  option  is  set  (see  below),  the 
.  exrc  file  in  the  current  directory  is  executed  after  EXINIT  or  the  HOME  directory  .exrc. 

The  editor  obtains  the  horizontal  and  vertical  size  of  the  terminal  screen  from  the  terminfo  database 
(see  terminfo(4)).  These  values  can  be  overridden  by  setting  the  UNIX95  environment  variable,  which 
specifies  to  use  the  XPG4  behavior  for  this  command.  COLUMNS  and  LINES  environment  variables.  See 
the  window  editor  option  below  for  more  information. 

The  foil  owing  table  shows  the  defaults  that  differ  for  the  various  editor  personalities: 


Name 

Default  Editor  Options 

edit 

nomagic 

novice 

noreadonly 

report=l 

showmode 

ex 

magic 

nonovice 

noreadonly 

report=5 

noshowmode 

vedit 

nomagic 

novice 

noreadonly 

report=l 

showmode 

vi 

magic 

nonovice 

noreadonly 

report=5 

noshowmode 

view 

magic 

nonovice 

readonly 

report=5 

noshowmode 

Editor  options  are  Boolean  unless  otherwise  specified.  Abbreviations  are  shown  in  parentheses. 

autoindent  (ai)  I  ndent  each  line  in  input  mode  (using  blanks  and  tabs)  to  align  with  the  previous  line. 

I  ndentation  begins  after  the  line  appended,  or  before  the  line  inserted  or  the  first  line 
changed.  Additional  indentation  can  be  provided  as  usual.  Succeeding  lines  are 
automatically  indented  to  the  new  alignment. 

Reducing  the  indent  is  achieved  by  typing  ~D  one  or  more  times:  the  cursor  is  moved 
back  to  the  next  multipleof  shiftwidth  spaces  for  each  "D.  A  "  followed  by  a  *D 
removes  all  indentation  temporarily  for  the  current  line.  A  0  followed  by  a  ~D 
removes  all  indentation. 

Reversed  by  noautoindent  (noai).  The  default  is  noautoindent . 

The  current  line  is  printed  after  each  command  that  changes  work  area  text.  Auto- 
print  is  suppressed  in  global  commands.  Reversed  by  noautoprint  (noap). 
The  default  isautoprint. 

The  work  area  is  written  out  to  the  current  file  if  the  work  area  has  been  modified  and 
a  next,  rewind,  or  !  command  is  given.  Reversed  by  noautowrite  (noaw). 
The  default  is  noautowrite. 

Cause  all  control  characters  other  than  tab,  newline,  and  formfeed  to  be  discarded 
from  the  input  text.  Reversed  by  nobeautify  (nobf).  The  default  is  nobeau- 
tify. 

directory=dirname  (dir) 

Specify  the  directory  in  which  the  editor  work  area  should  be  placed.  This  option  only 
takes  effect  when  a  new  work  area  is  created.  It  should  be  set  in  EXINIT  or  .  exrc 
to  affect  the  location  of  the  work  area  file  for  the  edit  file  specified  on  the  command 
line.  The  default  is /var/tmp. 

If  the  specified  directory  is  set  from  EXINIT  or  a  .exrc  file  and  is  not  writable  by 
the  user,  the  editor  quits;  if  set  interactively  by  the  user,  the  editor  issues  an  error 


autoprint  (ap) 
autowrite  (aw) 
beautify  (bf) 
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message. 

doubleescape     When  set,  two  consecutive  ESC  (escape)  characters  are  required  to  leave  input  mode. 

In  input  mode,  a  single  ESC  character  followed  by  a  different  character  causes  vi  to 
issuean  audibleor  visual  warning  (seethe  flash  editor  option)  and  insert  both  char- 
acters into  the  work  area.  Reversed  by  nodoubleescape.  The  default  is 
nodoubleescape. 

The  character  sequences  transmitted  by  the  keyboard  editing  keys  of  some  terminals 
are  identical  to  some  sequences  of  vi  user  commands.  If  the  mapping  of  these  keys  is 
enabled  (see  the  keyboardedit  and  keyboardedit !  options),  vi  might  not  be 
ableto  reliably  distinguish  between  the  character  sequence  transmitted  by  an  editing 
key  and  the  same  character  sequence  typed  by  a  user.  This  problem  is  most  likely  to 
occur  when  the  user  types  ESC  to  terminate  input  mode  immediately  followed  by 
another  vi  command.  If  you  set  the  doubleescape  option,  the  ambiguity  of  this 
case  is  removed. 

edcompatible  (ed) 

Cause  the  presence  of  g  and  c  suffixes  on  substitute  commands  to  be  remembered, 
and  toggled  by  repeating  the  suffixes.  Reversed  by  noedcompatible  (noed). 
The  default  is  noedcompatible. 

errorbells  (eb)  When  set,  error  messages  are  preceded  with  a  bell  only  on  terminals  that  do  not  sup- 
port a  standout  or  highlighting  mode  such  as  inverse  video.  If  the  terminal  supports 
highlighting,  the  bell  is  never  used  prior  to  error  messages  and  this  option  has  no 
effect.  Note  that  visual-mode  errors  are  signaled  by  the  bell  (regardless  of  the  setting 
of  this  option)  without  an  accompanying  error  message. 

Reversed  by  noerrorbells  (noeb).  The  default  is  noerrorbells  . 

When  set,  the  .exrc  file  in  the  current  directory  is  processed  during  editor  initializa- 
tion if  the  current  directory  is  not  the  HOME  directory.  This  option  is  not  set  by 
default  and  must  be  set  in  the  EXINIT  environment  variable  or  the  HOME  directory 
.exrc  file  to  have  any  effect.  See  the  Editor  Options  introductory  text  above. 
Reversed  bynoexrc.  The  default  is  noexrc. 

When  set,  the  screen  flashes  instead  of  beeping,  provided  an  appropriate 
flash_screen  entry  is  present  in  the  /usr/share/lib/terminf o  database 
for  the  terminal  beingused.  Reversed  by  nof  lash  (nofl).  The  default  is  flash. 

hardtabs=  number  (ht) 

Define  the  spacing  between  hardware  tab  settings  and  the  number  of  spaces  used  by 
the  system  when  expanding  tab  characters.  Tab  stops  are  placed  in  each  column 
number  (starting  at  the  left  edge  of  the  screen)  that  corresponds  to  an  integer  multi- 
ple of  number.  The  default  ishardtabs=8  . 

ignorecase  (ic)  All  uppercase  characters  in  the  text  are  mapped  to  lowercase  in  regular  expression 
matching.  Also,  all  uppercase  characters  in  regular  expressions  are  mapped  to  lower- 
case, except  in  character  class  specifications.  Reversed  by  noignorecase  (noic). 
The  default  is  noignorecase  . 

keyboardedit  When  set,  any  keyboard  editing  key  mappings  that  are  loaded  automatically  at  initial- 
ization for  command-mode  use  are  enabled.  If  not  set,  these  mappings  are  disabled 
(but  not  deleted).  Use  the  map  command  to  get  a  list  of  the  currently  enabled 
command-mode  mappings.  Reversed  by  nokeyboardedit.  The  default  is  key- 
boardedit . 

keyboardedit !  When  set,  the  keyboard  editing  key  mappings  automatically  loaded  at  initialization  for 
input  mode  use  are  enabled.  If  not  set,  these  mappings  are  disabled  (but  not  deleted). 
Use  the  map!  command  to  list  the  currently  enabled  input-mode  mappings.  Reversed 
by  nokeyboardedit ! .  The  default  is  nokeyboardedit !  for  terminals  whose 
keyboard  editing  keys  send  HP-style  escape  sequences  (an  ESC  followed  by  a  single 
letter).  The  default  is  keyboardedit !  for  all  other  terminals. 

lisp  Modify  autoindent  mode  and  the  (,  ) ,  [[,]],{,  and  }  commands  in  visual  mode 

for  lisp  source  code.  Reversed  by  nolisp.  The  default  is  nolisp. 

list  Display  all  printed  lines  with  tabs  shown  as  "I,  and  the  end  of  line  marked  by  a  $. 

Reversed  by  nolist .  The  default  is  nolist . 


exrc 


flash  (fl) 


HP-UX  Release  Hi:  December  2000 


-13- 


Section  1-253 


ex(l) 


ex(l) 


magic 


mesg 


model ines  (ml) 


number  (nu) 


optimize  (opt) 


Affect  the  interpretation  of  characters  in  regular  expressions  and  substitution  replace- 
ment strings  (see  Regular  Expressions  and  Replacement  Strings  above).  Reversed  by 
nomagic.  Theex,  vi,  and  view  default  ismagic.  The  edit  and  vedit  default 
isnomagic. 

Allows  other  users  to  use  the  write  command  (see  write(l))  to  send  messages  to 
your  terminal,  possibly  disrupting  the  screen  display.  Unsetting  this  option 
(nomesg)  blocks  write  permission  to  your  terminal  from  other  system  users  while 
you  are  using  the  editor.  Reversed  by  nomesg.  The  default  is  mesg. 

If  set  when  the  editor  reads  in  a  file,  any  ex  commands  embedded  in  the  first  five  and 
last  five  lines  of  the  file  are  executed  after  .exrc  and  EXINIT  commands  are  pro- 
cessed but  before  editing  control  is  given  to  the  user.  The  ex  commands  must  be 
prefixed  by  ex :  or  vi :  and  terminated  by  :  in  a  single  line.  Any  number  of  other 
characters  with  the  exception  of  the  colon  (: )  can  precede  or  follow  the  embedded 
command.  Reversed  by  nomodelines  (noml).  The  default  is  nomodelines  . 

Use  the  version  of  the  editor  available  for  novices,  known  as  edit  or  vedit. 
Reversed  by  nonovice .  The  ex,  vi,  and  view  default  is  nonovice .  The  edit, 
and  vedit  default  is  novice . 

Cause  lines  to  be  printed  with  line  numbers.  Reversed  by  nonumber  (nonu).  The 
default  is  nonumber. 

Suppress  automatic  carriage  returns  on  terminals  that  do  not  support  direct  cursor 
addressing.  This  streamlines  text  output  in  certain  situations  such  as  when  printing 
multiplelinesthat  contain  leading  whitespace.  Reversed  bynooptimize  (noopt). 
The  default  isnooptimize . 

paragraphs=  pair-string  (para) 

The  value  of  this  option  is  a  string  whose  successive  pairs  of  characters  specify  the 
names  of  text-processing  macros  that  begin  paragraphs.  (A  macro  appears  in  the  text 
intheform  .xx,  where  the  .  isthe  first  character  in  the  line.) 

If  any  macros  have  a  single-character  name,  use  a  space  character  to  substitute  for 
the  missing  second  character  in  the  name.  To  type  a  space  character  in  such  situa- 
tions, precede  the  space  with  a  backslash  (\)  to  prevent  the  editor  from  interpreting  it 
as  a  delimiter. 

Thedefault  isparagraphs=IPLPPPQPP\  LIpplpipnpbp. 

prompt  When  set,  command  mode  input  is  prompted  for  with  a  colon  (:);  when  unset,  no 

prompt  is  displayed.  Reversed  by  noprompt .  Thedefault  is  prompt. 

readonly  (ro)  Set  the  readonly  flag  for  the  file  being  edited,  thus  preventing  accidental  overwrit- 
ing at  the  end  of  the  session.  This  option  is  equivalent  to  invoking  ex,  edit,  vi,  or 
vedit  with  the  -R  option  or  using  the  view  command.  Reversed  by 
noreadonly  (noro).  The  ex,  edit,  vi,  and  vedit  default  is  noreadonly. 
Theview  default  is  readonly. 

redraw  Simulate  an  intelligent  terminal  on  a  dumb  terminal.  During  input  mode,  lines  are 

continuously  reprinted  as  text  is  entered.  Since  this  is  likely  to  require  a  large 
amount  of  output  to  the  terminal,  it  is  useful  only  at  high  transmission  speeds.  If 
noredraw  is  set,  lines  are  reprinted  only  when  input  mode  is  terminated  and 
deleted  lines  are  marked  with  an  @  in  the  left  margin.  Reversed  by  noredraw .  The 
default  is  redraw. 

remap  If  set,  macro  translation  allows  for  macros  defined  in  terms  of  other  macros;  transla- 

tion continues  until  the  final  product  is  obtained.  If  unset,  a  one-step  translation  only 
isdone.  Reversed  by  noremap .  Thedefault  is  remap. 

report=n  The  value  of  n  gives  the  number  of  lines  that  must  be  changed  by  a  command  beforea 

report  is  displayed  on  the  number  of  lines  affected.  If  n  is  5,  then  changes  are 
reported  for  6  or  more  lines.  The  ex,  vi,  and  view  default  is  report=5.  The 
edit,  and  vedit  default  is  report=l . 

scroll=n  The  value  of  n  determines  the  number  of  lines  scrolled  by  a  ~D  command  and  the 

number  of  lines  displayed  by  the  z  command  (twice  the  value  of  scroll).  Thedefault  is 
half  the  value  of  the  window  option. 
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sections=  pai  r-stri  ng 


The  value  of  this  option  is  a  string,  in  that  successive  pairs  of  characters  specify  the 
names  of  text-processing  macros  that  begin  sections.  See  the  paragraphs  editor 
option  above.  The  default  is  sections=NHSHH\  HUuhsh+c. 


Set  the  file  name  of  the  shell  to  be  used  for  the  !  shell  escape  and  the  shell  com- 
mand. It  defaults  to  the  value  of  your  SHELL  environment  variable,  if  set,  and  other- 
wise to  /usr/bin/sh. 


shif twidth=  n  (sw) 

Sets  the  indentation  step  value  used  by  autoindent  and  the  shift  (<  and  >)  com- 
mands. The  default  is  shiftwidth=8  . 

showmatch  (sm)  In  visual  mode,  jump  momentarily  to  the  matching  (  or  {  when  you  type  a  )  or  },  if 
the  match  is  still  on  the  screen.  Reversed  by  noshowmatch  (nosm).  Thedefaultis 
no showmatch . 

showmode  (smd)    Display  the  current  editor  mode  (such  as  INPUT   MODE,  REPLACE    1  CHAR, 


REPLACE  MODE)  in  the  lower  right-hand  corner  of  the  screen  during  visual  and  open 
mode.  Reversed  by  noshowmode  (nosmd).  The  ex,  vi,  and  view  default  is 
noshowmode  .  The  edit,  and  vedit  default  is  showmode . 


slowopen  (slow)  In  visual  mode,  slowopen  prevents  screen  updates  during  input  to  improve 
throughput  on  unintelligent  terminals.  Reversed  by  noslowopen  (noslow).  The 
default  is  noslowopen . 

tabstop=n  (ts)  Sets  the  spacing  of  the  software  tab  stops  used  by  the  editor  to  expand  tabs  in  the 
input  file.  The  default  is  tabstop=8. 

taglength=n  (tl) 


Set  the  maximum  number  of  characters  that  should  be  treated  as  significant  in  a  tag. 
Characters  beyond  the  limit  are  ignored.  A  value  of  zero  means  that  all  characters  in 
the  tag  are  significant.  The  default  is  taglength=0  . 


tags=[filename  ]...  Specify  the  tags  files  to  be  used  by  the  tag  command  and  the  -t  command-line 


option.  The  default  is  tags=tags  /usr/lib/tags,  specifying  the  file  tags  in 
the  current  directory  and  the  file  /usr/lib/tags.  File  names  are  separated  by 
whitespace. 

Each  line  of  a  tags  file  contains  the  following  three  fields  separated  by  whitespace: 
the  tag  name,  the  name  of  the  file  to  be  edited,  and  an  address  specification  (see 
Addressing  above).  A  tags  file  must  be  sorted  in  order  by  tag  name. 

The  ctags  command  (see  ctags(l))  creates  tags  files  from  C,  Pascal  and  FORTRAN 
source  files. 


tagstack  (tgst)  Enablethe  pushdown  stack  of  activated  tags.  Reversed  by  notagstack  (notgst). 
The  default  is  tagstack. 


When  you  enter  a  line  mode  tag  command  or  visual  mode  "  ]  command,  the  current 
line  number  and  file  name  are  stored  on  the  tag  stack.  A  future  line  mode  pop  com- 
mand or  visual  mode  "T  command  will  return  to  the  stored  file  name  at  the  stored 
line  number. 

If  the  tag  stack  is  disabled  and  then  reenabled  again,  the  stack  continues  where  it  left 
off.  Thepop  command  does  not  work  when  the  tag  stack  is  disabled. 


term=termtype       Define  the  type  of  terminal  being  used  with  the  editor.  The  default  value  is  obtained 


from  the  TERM  environment  variable.  If  TERM  is  unset  or  null,  term  is  set  to 
unknown.  There  is  no  difference  between  the  term  and  ttytype  editor  options. 
Setting  either  one  results  in  both  being  changed. 


timeout  (to)       If  set,  require  that  all  the  characters  of  a  multicharacter  macro  name  (the  first  argu- 


ment in  a  map  command)  must  be  received  within  the  amount  of  time  specified  by  the 
timeoutlen  option  in  order  to  be  accepted  as  a  match  for  the  macro  name.  If  not 
set,  no  limit  is  placed  on  how  long  to  wait  for  the  completion  of  a  macro  name. 
Reversed  by  notimeout  (noto).  The  default  is  timeout. 


shell=filename  (sh) 


terse 


Use  shorter  error  messages.  Reversed  by  noterse.  The  default  isnoterse. 
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timeoutlen=  n  Set,  in  milliseconds  (ms),  the  length  of  the  macro  timeout  period  (see  the  timeout 
editor  option).  This  option  has  no  effect  unless  timeout  isset.  The  value  of  n  must 
beat  least  1.  The  default  is  timeoutlen=500  (half  a  second). 

ttytype=termtype  (tty) 

Define  the  type  of  terminal  being  used  with  the  editor.  See  the  term  editor  option 
for  details.  There  is  no  difference  between  the  term  and  ttytype  editor  options. 
Setting  either  one  results  in  both  being  changed. 

warn  Before  executing  a  !  or  shell  command  escape,  display  the  message  [No  write 

since  last  change]  if  the  work  area  has  been  modified  since  it  was  last  loaded 
or  fully  written  to  a  file.  Reversed  by  nowarn .  The  default  is  warn. 

window=  lines  (wi) 

Set  the  number  of  lines  in  a  text  window  in  visual  mode.  The  default  value  is  one  less 
than  the  size  of  your  terminal  screen  (as  defined  by  the  LINES  environment  variable, 
if  set,  or  the  entry  for  your  terminal  in  the  terminfo(4)  data  base  otherwise).  How- 
ever, if  the  terminal  baud  rate  (see  stty(l)  is  set  to  less  than  1200  or  2400,  the  default 
value  is  reduced  toa  maximumof  8or  16lines,  respectively.  The  startup  value  can  be 
specified  with  the-w  command-line  option. 

w300=lines  If  the  terminal  baud  rate  is  less  than  1200,  set  the  window  editor  option  to  the  value 

specified. 

wl200=lines  If  the  terminal  baud  rate  is  greater  than  or  equal  to  1200  but  less  than  2400,  set  the 

window  editor  option  to  the  value  specified. 

w9 600= lines  If  the  terminal  baud  rate  is  greater  than  or  equal  to  2400,  set  the  window  editor 

option  to  the  value  specified. 

wrapmargin=  n  (wm) 

I  n  visual  mode  only,  if  n  is  greater  than  zero,  a  newline  is  automatically  inserted  in  an 
input  line  at  a  word  boundary,  so  that  lines  end  at  least  n  spaces  from  the  right  mar- 
gin of  the  terminal  screen.  Thedefault  is  wrapmargin=0  . 

wrapscan  (ws)  When  set,  editor  searches  using /re/ (or  ?re?)  continue  silently  from  the  beginning 
(or  end)  of  the  file  upon  reaching  the  end  (or  beginning)  of  the  file  (that  is,  the  scan 
"wraps  around").  When  unset,  editor  searches  stop  at  the  beginning  or  the  end  of  the 
file,  as  appropriate.  Reversed  by  nowrapscan  (nows).  Thedefault  is  wrapscan. 

writeany  (wa)  Inhibits  the  checks  otherwise  made  before  write  commands,  allowing  a  write  to  any 
file  (provided  the  system  allows  it).  Reversed  by  nowriteany  (nowa).  Thedefault 
is  nowriteany . 

EXTERNAL  INFLUENCES 
Environment  Variables 

COLUMNS  This  variableshall  override  the  system-selected  horizontal  screen  size. 

LINES  overrides  the  system-selected  vertical  screen  size,  used  as  the  number  of  lines  in  a  screenful  and  as 
the  vertical  screen  sizein  visual  mode. 

PATH  determines  the  search  path  for  the  shell  command  specified  in  the  editor  commands,  shell,  read, 
and  write. 

SHELL  is  variable  that  shall  be  interpreted  as  the  preferred  command-line  interpreter  for  use  in  !, 
shell,  read,  and  other  commands  with  an  operand  of  the  form  !  string.  For  the  shell  command, 
the  program  shall  be  invoked  with  the  single  argument  -i.  For  all  others,  it  shall  be  invoked  with  the  two 
arguments  -c  and  string.  If  no  SHELL  environment  variable  is  set,  or  it  is  set  to  a  null  string,  the  sh 
utility  shall  be  used. 

TERM  is  a  variablethat  shall  be  interpreted  as  the  name  of  the  terminal  type.  If  this  variable  is  unset  or 
null,  an  unspecified  default  terminal  type  shall  be  used. 

EXINIT  is  a  variablethat  shall  be  i nterpreted  to  contain  a  list  of  ex  commands  that  are  executed  on  edi- 
tor startup,  before  reading  the  first  file.  The  list  can  contain  multiple  commands  by  separating  then  using  a 
vertical  line(|  )  character. 

HOME  shall  be  interpreted  as  a  pathname  of  a  directory  that  shall  be  searched  for  an  editor  startup  file 
name .exrc. 
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LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  regular  expressions  and  in  processing 
the  tags  file.  If  it  is  not  specified  or  is  null,  it  defaults  to  the  value  of  LANG. 

LC_CTYPE  determines  the  interpretation  of  text  as  singleand/or  multibyte  characters,  the  classification  of 
characters  as  uppercase  or  lowercase  letters,  the  shifting  of  the  case  of  letters,  and  the  characters  matched 
by  character  class  expressions  in  regular  expressions.  If  it  is  not  specified  or  is  null,  it  defaults  to  the  value 

Of  LANG. 

LANG  determines  the  language  in  which  messages  are  displayed.  If  it  is  not  specified  or  is  null,  it  defaults 
to  "C"  (seelang(5)). 

LC_ALL  determines  the  locale  to  be  used  to  override  any  values  for  locale  categories  specified  by  the  set- 
tingof  LANG  or  any  environment  variable(beginning  with  LC_  ). 

LC_ME S SAGE S  determines  the  processing  of  affirmative  responses  and  the  language  in  which  messages 
should  be  written. 

If  any  internationalization  variable  contains  an  invalid  setting,  all  internationalization  variables  default  to 
"C"  (see environ (5)). 

When  set,  the  TMPDIR  environment  variablespecifies  a  directory  to  be  used  for  temporary  files,  overriding 
the  default  directory  /var/tmp. 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

ASYNCHRONOUS  EVENTS  (XPG4  Only) 

The  foil  owing  actions  shall  betaken  upon  receipt  of  signals: 

SIGINT 

When  an  interrupt  occurs,  ex  shall  alert  the  terminal  and  write  a  message.  The  current  editor  com- 
mand shall  be  aborted,  and  ex  shall  return  to  the  command  level  and  prompt  for  another  command. 
If  the  standard  input  is  not  a  terminal  device,  ex  shall  exit  at  the  interrupt  and  return  a  nonzero  exit 
status. 

SIGCONT 

The  screen  shall  be  refreshed. 

SHIGHUP 

If  the  current  buffer  has  changed  since  the  last  e  or  w  command,  ex  shall  attempt  to  save  the 
current  file  in  a  statesuch  that  it  can  be  recovered  later  by  an  ex  -r  command. 

The  action  taken  for  all  other  signals  is  unspecified. 

EXTENDED  DESCRIPTION  (XPG4  0nly) 

The  pathname  of  the  file  being  edited  by  ex  is  referred  to  as  the  current  file.  The  text  of  the  file  shall 
be  read  into  a  working  version  of  the  file  (called  buffer  in  this  clause),  and  all  editing  changes  shall  be 
performed  on  that  version;  the  changes  shall  have  no  effect  on  the  original  file  until  an  ex  command 
causes  the  file  to  be  written  out.  Lines  in  the  buffer  may  be  limited  to  {  LINE_MAX  } bytes,  and  an  error 
message  may  be  written  if  the  limit  is  exceeded  during  editing. 

The  alternate  pathname  is  the  name  of  the  last  file  mentioned  in  an  editor  command,  or  the  previous 
current  pathname  if  the  last  file  mentioned  became  the  current  file.  When  the  %  appears  in  a  pathname 
entered  as  part  of  a  command  argument,  it  shall  be  replaced  by  the  altername  pathname.  Any  character, 
including  %  and  #  shall  retain  its  literal  value  when  preceded  by  a  backslash. 

When  an  error  occurs,  ex  shall  alert  ther  terminal  and  write  a  message. 

If  the  system  crashes,  ex  shall  attempt  to  preserve  the  buffer  if  any  unwritten  changes  were  made.  The 
command-line  option  -r  can  be  used  to  retrieve  the  saved  changes. 

During  initialization  (before  the  first  file  is  read  or  any  user  commands  from  the  terminal  are  processed),  if 
the  environment  variable  EXINIT  is  set,  the  editor  shall  execute  ex  commands  contained  in  that  vari- 
able. If  the  variable  is  not  set,  ex  shall  attempt  to  read  commands  from  the  $HOME/  .  exrc .  If  and  only 
if  EXINIT  or  $HOME/.exrc  sets  the  editor  option  exrc,  ex  finally  shall  attempt  to  read  commands  from 
a  file  .exrc  in  the  current  directory.  In  the  event  that  EXINIT  is  not  set  and  the  current  directory  is 
the  home  directory  of  the  user,  any  .exrc  file  shall  only  be  processed  once.  No  .exrc  shall  be  read 
unless  it  is  owned  by  the  same  user  I D  as  the  effective  user  I D  of  the  process.  After  any  .  exrc  files  are 
processed,  any  commands  specified  by  the  -c  option  shall  be  processed. 
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By  default,  ex  shall  start  in  the  command  mode,  which  shall  be  indicated  by  the  ":"  prompt.  The  input 
mode  can  be  entered  by  append,  insert ,  or  change  commands.  There  is  one  other  mode,  visual  mode, 
in  which  full  screen  editing  is  available.  This  is  described  more  fully  under  the  visual  command.  The 
command  line  can  consist  of  multiple  ex  commands  separated  by  vertical-line  characters(|  ).  The  use  of 
commands  that  enter  input  or  visual  modes  in  this  manner,  unless  they  are  the  final  command  on  the  line, 
produces  undefined  results. 

Command  lines  beginning  with  the  double-quote  character  (")  shall  be  ignored.  This  can  be  used  for  com- 
ments in  an  editor  script. 

WARNINGS 

The  undo  command  causes  all  marks  to  be  lost  on  lines  that  are  changed  and  then  restored. 

The  z  command  prints  a  number  of  logical  rather  than  physical  lines.  More  than  a  screenful  of  output  can 
result  if  long  lines  are  present. 

Null  characters  are  discarded  in  input  files  and  cannot  appear  in  resultant  files. 

On  some  systems,  the  recovery  of  an  edit  file  with  the  -r  option  is  possible  only  if  certain  system- 
dependent  actions  are  taken  when  the  system  is  restarted. 

Edit  preserve  files  can  only  be  recovered  on  systems  running  the  same  HP-UX  release  in  which  they  were 
preserved.  Preserve  files  are  not  recoverable  across  different  releases. 

On  HP  terminals,  the  attribute  field  of  any  function  key  specified  by  a  map  #n  ...  command  should  beset 
to  normal  rather  than  to  the  default  of  transmit . 

Do  not  use  the  -C  option  to  edit  unencrypted  files.  The  -C  option  is  meant  to  be  used  only  on  files  that  are 
already  encrypted.  If  the  -C  option  is  used  on  files  which  are  not  yet  encrypted,  a  write  in  the  edit  session 
is  likely  to  corrupt  the  file. 

For  information  about  line  length  limits,  file  size  limits,  etc.,  see  the  WARN  I NGS  section  of  vi  (1). 

EXIT  STATUS  (XPG4  0nly) 

Theex  utility  shall  exit  with  one  of  the  foil  owing  values: 

0     Successful  completion. 
>0    An  error  occurred. 


ex  was  developed  by  the  University  of  California,  Berkeley.  The  16-bit  extensions  to  ex  are  based  in  part 
on  software  of  the  Toshiba  Corporation. 


SEE  ALSO 

ctags(l),  ed(l),  stty(l),  vi(l),  write(l),  terminfo(4),  environ(5),  lang(5),  regexp(5). 

TheUltimateGuidetothevi  and  ex  Text  Editors,  Benjamin/Cummings  Publishing  Company,  Inc.,  ISBN  0- 
8053-4460-8,  H  P  part  number  97005-90015. 

STANDARDS  COMPLIANCE 

ex:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 


AUTHOR 


FILES 


$HOME/ . exrc 
. / . exrc 

/ usr/ lbin/ expreserve 

/ usr/ lbin/ exrecover 

/usr/ share/lib/terminf o/*/* 

/var/preserve 

/var/tmp/Ex  nnnnn 

/var/tmp/Rx  nnnnn 


Primary  editor  initialization  file 

Secondary  editor  initialization  file 

Preserve  command 

Recover  command 

Description  of  terminal  capabilities 

Preservation  directory 

Editor  temporary  file 

Named  buffer  temporary  file 
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NAME 

expand,  unexpand  -  expand  tabs  to  spaces,  and  vice  versa 

SYNOPSIS 

expand  [-t  tablist]  [file  ...] 

unexpand  [-a]  [-t  tablist]  [file  ...] 

Obsolescent: 

expand  [-tabstop]  [-tabl,  tab2, ... ,  tabn  ]  [file  ...] 

DESCRIPTION 

expand  processes  the  named  files  or  the  standard  input  and  writes  to  the  standard  output  with  tabs 
changed  into  spaces.  Backspace  characters  are  preserved  in  the  output,  and  the  column  count  is  decreased 
by  one  column  for  tab  calculations.  For  proper  tab  calculation,  if  a  multi-column  character  is  to  be 
"backspace'd",  it  should  be  foil  owed  by  multiple  backspace  characters  which  equal  to  it's  column  width.  If  a 
tab  character  is  found  after  the  last  tab  position,  it  is  replaced  by  a  single  space,  expand  is  useful  for 
preprocessing  character  files  that  contain  tabs  (before  sorting,  looking  at  specific  columns,  etc). 

expand  recognizes  the  following  command-line  options  and  arguments: 

[-t  tablist]  tablist  specifies  where  to  set  the  tab  positions  instead  of  the  default  8.  tablist  can 
take  two  forms.  If  it  is  a  single  number,  tabs  are  set  tablist  spaces  apart,  tablist  can 
also  be  a  blank-  or  comma-separated  list  of  increasing  positions  where  tabs  are  to  be 
set. 

[-tabstop]       This  option  is  obsolescent  and  is  equivalent  to  using -t  tabstop. 

[-tabl,  tab2,...,  tabn] 

This  option  is  obsolescent  and  is  equivalent  to  using  -ttabl,tab2,   ...  ,tabn. 

unexpand  processes  the  named  files  or  the  standard  input  and  writes  to  the  standard  output  with  spaces 
changed  into  tabs  where  possible.  By  default,  only  leading  spaces  and  tabs  are  converted  to  maximal 
stri  ngs  of  tabs.  The  default  tab  position  is  every  8  characters.  Backspace  characters  are  preserved  intothe 
output,  and  the  column  count  is  decreased  by  one  column  for  tab  calculations.  For  proper  tab  calculation,  if 
a  multi-column  character  is  to  be  "backspace'd",  it  should  be  followed  by  multiple  backspace  characters 
which  equal  to  it's  column  width. 

unexpand  recognizes  the  following  command-line  options  and  arguments: 

-a  Tabs  are  inserted  whenever  they  would  compress  the  resultant  file  by  replacing  two  or 

more  spaces  before  a  tab  position. 

-t  tablist  tablist  specifies  the  tab  positions,  tablist  can  take  two  forms.  If  it  is  a  single  number, 
tabs  are  set  every  tablist  spaces  apart.  If  tablist  is  a  blank-  or  comma-separated  list  of 
increasing  positions,  tabs  are  set  at  those  locations.  The  -t  option  implies  the  -a 
option.  If  the  -t  option  is  not  specified,  the  default  is  equivalent  to  specifying  -t  8 
except  that  -a  is  not  implied  for  this  case. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  expand  and  unexpand  behave  as  if  all 
internationalization  variables  are  set  to  "C".  See  environ  (5). 

If  LC_ALL  is  set  to  a  non-empty  string  value,  it  overrides  the  values  of  all  the  other  internationalization 
variables. 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported  with  the  exception  that  unexpand  do  not  recog- 
nize multi-byte  alternative  space  characters. 
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STANDARDS  CONFORMANCE 

expand:  XPG4,  P0SIX.2 

unexpand:  XPG4,  P0SIX.2 
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NAME 

expandalias-  recursively  expands  the  sendmail  aliases 
SYNOPSIS 

expand_alias  [-rmaxrecursion]  [-t]  [-tt]  alias 
DESCRIPTION 

Expand_alias  is  a  shell  script  that  recursively  expands  the  sendmail  aliases.  Through  use  of  tel- 
net host  25  and  the  expn  command,  each  alias  is  recursively  expanded  into  its  destination(s).  I  nden- 
tation  is  used  to  show  each  level  of  recursion.  Because  of  the  recursive  use  of  telnet,  expand_alias 
is  slow.  If  the  local  telnet  cannot  directly  connect  to  a  remote  system,  due  to  a  firewall  configuration, 
expand_alias  will  not  be  able  to  succeed.  If  the  local  telnet  is  to  transparently  connect  across  the 
firewall,  expand_alias  will  be  able  to  contact  sendmail  daemons  outside  the  firewall,  allowing  the  alias 
to  be  more  fully  expanded.  (For  example,  some  local  telnet  clients  use  a  socksd  located  on  the  firewall  to 
permit  the  local  telnet  client  to  transparently  connect  to  Internet  hosts.  If  the  local  default  telnet 
uses  a  socksd  in  such  a  manner,  expand_alias  will  use  that  telnet  functionality  to  more  fully 
expand  an  alias.) 

maxrecursion  defaults  to  10.  After  maxrecursion  expansions,  no  further  expansion  is  attempted. 
If-t  isspecified,  only  the  terminal  aliases  will  be  displayed. 

-tt  is  similar  to  -t  except  that  if  a  terminal  line  has  a  pipe,  its  printing  is  suppressed  and  the  previous 
level  of  expansion  is  printed  instead. 

EXAMPLES 

expand_alias  root 

expand_alias  root @ cat 
expand_alias  root@cat.cup.hp.com 
expand_alias  root@cup.hp.com 

AUTHOR 

expand_alias  was  developed  by  the  Hewlett-Packard  Company. 
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NAME 

expr  -  evaluate  arguments  as  an  expression 


SYNOPSIS 

expr  arguments 


DESCRIPTION 

expr  takes  arguments  as  an  expression,  evaluates,  then  writes  the  result  on  the  standard  output.  Terms 
in  the  expression  must  be  separated  by  blanks.  Characters  special  to  the  shell  must  be  escaped.  Note  that 
0,  rather  than  the  null  string,  is  returned  to  indicatea  zero  value.  Strings  containing  blanks  or  other  spe- 
cial characters  should  be  quoted.  Integer-valued  arguments  can  be  preceded  by  a  unary  minus  sign.  Inter- 
nally, integers  are  treated  as  32-bit,  2's  complement  numbers. 

The  operators  and  keywords  are  listed  below.  Characters  that  need  to  be  escaped  are  preceded  by  \.  The 
list  is  in  order  of  increasing  precedence  with  equal -precedence  operators  grouped  within  { }  symbols. 

expr  \|  expr       Returns  the  first  expr  if  it  is  neither  null  nor  0,  otherwise  returns  the  second  expr. 

expr  \&  expr       Returns  the  first  expr  if  neither  expr  is  null  or  0,  otherwise  returns  0. 

expr  {  =,  \>,  \>=,  \<,  \<=,  !=}expr 

If  both  arguments  are  integers,  and  if  the  comparison  is  satisfied,  expr  returns  1  other- 
wise it  returns  0.  expr  returns  the  result  of  an  integer  comparison  if  both  arguments 
are  integers;  otherwise  returns  the  result  of  a  lexical  comparison  (note  that  =  and  == 
are  identical,  in  that  both  test  for  equality). 

expr  {  +,  -  }  expr 

Addition  or  subtraction  of  decimal  integer-valued  arguments. 

expr  {  \*,  /,  %  }  expr 

Multiplication,  division  or  remainder  of  decimal  integer-valued  arguments  producing  an 
integer  result. 

expr  :  expr  The  matching  operator  :  compares  the  first  argument  with  the  second  argument  which 
must  be  a  regular  expression,  expr  supports  the  Basic  Regular  Expression  syntax  (see 
regexp(5)),  except  that  all  patterns  are  "anchored"  (i.e.,  begin  with  ")  and,  therefore,  " 
is  not  a  special  character,  in  that  context.  Normally,  the  matching  operator  returns  the 
number  of  characters  matched  (O  on  failure).  Alternatively,  the  \  ( ...  \)  pattern  sym- 
bols can  be  used  to  return  a  portion  of  the  first  argument. 

length  expr       The  length  of  expr. 

substr  expr  expr  expr 

Takes  the  substring  of  the  first  expr,  starting  at  the  character  specified  by  the  second 
expr  for  the  length  given  by  the  third  expr. 

index  expr  expr  Returns  the  position  in  the  first  expr  which  contains  a  character  found  in  the  second 
expr. 

match  Match  is  a  prefix  operator  equivalent  to  the  infix  operator  :. 

\(...\)  Grouping  symbols.  Any  expression  can  be  placed  within  parentheses.  Parentheses  can 

be  nested  to  a  depth  of  EXPR_NEST_MAX  as  specified  in  the  header  file 
<limits  .h>. 


EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  regular  expressions  and  the  behavior 
of  the  relational  operators  when  comparing  string  values. 

LC_CTYPE  determines  the  interpretation  of  text  as  single-  and/or  multi-byte  characters,  and  the  charac- 
ters matched  by  character  class  expressions  in  regular  expressions. 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_COLLATE  or  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  expr  behaves  as  if  all  internationalization  variables  are  set  to  "C"  (see 
envi  ron(5)). 
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I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

As  a  side  effect  of  expression  evaluation,  expr  returns  the  foil  owing  exit  values: 

0  Expression  is  neither  null  nor  zero. 

1  E  xpressi  on  i  s  n  u  1 1  or  zero. 

2  I  nval id  expression. 

>2      An  error  occurred  while  evaluating  the  expression. 

DIAGNOSTICS 

syntax  error  Operator  or  operand  errors 

non-numeric  argument  Arithmetic  attempted  on  a  string 

EXAMPLES 

Add  lto  the  shell  variablea: 

a='expr  $a  +  1 ' 

For  $a  equal  to  either  /usr/abc/f ile  or  just  file,  return  the  last  segment  of  a  path  name  (i.e., 
file).  Beware  of  /  alone  as  an  argument  because  expr  interprets  it  as  the  division  operator  (see  warn- 
ings below): 

expr  $a  :   '  .*/\(.*\) '    \|  $a 

A  better  representation  of  the  previous  example.  The  addition  of  the  //  characters  eliminates  any  ambi- 
guity about  the  division  operator  and  simplifies  the  whole  expression: 

expr  //$a   :    ' .*/\(.*\) ' 

Return  the  number  of  characters  in  $VAR: 

expr  $var  :    '  .  * ' 

WARNINGS 

After  argument  processing  by  the  shell,  expr  cannot  tell  the  difference  between  an  operator  and  an  operand 
except  by  the  val ue.  If  $a  is  an  =,  the  command: 

expr  $a  =  '=' 

resembles: 

expr  =  =  = 

as  the  arguments  are  passed  to  expr  (and  they  will  all  betaken  as  the  =  operator).  The  foil  owing  works: 
expr  X$a  =  X= 

AUTHOR 

expr  was  developed  by  OSF  and  HP. 

SEE  ALSO 

sh(l),  test(l),  environ(5),  lang(5),  regexp(5). 

STANDARDS  CONFORMANCE 

expr:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

factor,  primes  -  factor  a  number,  generate  large  primes 

SYNOPSIS 

factor  [number] 

primes  [  start  [  stop  ]  ] 
DESCRIPTION 

If  no  arguments  are  provided  on  the  command  line,  factor  waits  for  a  number  to  be  typed  in.  If  a  posi- 
tive number  is  typed,  it  factors  the  number  and  print  its  prime  factors;  each  one  is  printed  the  proper 
number  of  times.  It  then  waits  for  another  number,  factor  exits  if  it  encounters  a  zero  or  any  non- 
numeric  character. 

If  an  argument  is  provided  on  the  command  line,  factor  factors  the  number  as  above,  then  exits. 
Maximum  time  to  factor  is  proportional  to  sqrt(n)  and  occurs  when  n  is  prime  or  the  square  of  a  prime. 
The  largest  number  that  can  be  dealt  with  by  factor  isl.0el4. 

primes  prints  prime  numbers  between  a  lower  and  upper  bound.  If  no  arguments  are  provided  on  the 
command  line,  primes  waits  for  two  numbers  to  be  typed  in.  The  first  number  is  interpreted  as  the 
lower  bound;  the  second  as  the  upper  bound.  All  prime  numbers  in  the  resulting  inclusive  range  are 
printed. 

If  start  is  specified,  all  primes  greater  than  or  equal  to  start  are  printed.  If  both  start  and  stop  are  given, 
all  primes  occurring  in  the  inclusive  range  start  through  stop  are  printed. 

start  and  stop  values  must  be  integers  represented  as  long  integers. 

If  the  stop  value  is  omitted  in  either  case,  primes  runs  either  until  overflow  occurs  or  until  it  is  stopped 
by  typi  ng  the  i  nterrupt  character. 

The  largest  number  that  can  be  dealt  with  by  primes  is  2,147,483,647. 
DIAGNOSTICS 

Both  commands  print  Ouch  when  the  input  is  out  of  range,  illegal  characters  are  encountered,  or  when 
start  is  greater  than  stop. 

EXAMPLES 

Print  the  prime  factorization  for  the  number  12: 

factor  12 

Print  all  prime  numbers  between  0  and  20: 
primes  0  20 
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NAME 

fastbind  -  prepare  an  incomplete  executable  for  faster  program  start-up 

SYNOPSIS 

fastbind  [-nu]  incomplete-executable... 

DESCRIPTION 

fastbind  is  a  tool  that  can  improve  the  start-up  time  of  programs  that  use  shared  libraries  (incomplete 
executables)  by  storing  information  about  needed  shared  library  symbols  in  the  executable  file. 

fastbind  performs  analysis  on  the  symbols  used  to  bind  an  executable  and  all  of  it's  dependent  shared 
libraries,  and  stores  this  information  in  the  executable  file.  The  next  time  the  executable  is  run,  the 
dynamic  loader  (/usr/lib/dld.  si  for  32-bit  PARISC  or  /usr/lib/pa20_64/dld.  si  for  64-bit 
PARISC)  will  notice  that  this  information  is  available,  and  it  will  use  this  fastbind  information  to  bind  the 
executable  instead  of  the  standard  search  method  for  binding  the  symbols. 

Since  fastbind  writes  the  fastbind  information  in  the  executable  file,  you  must  have  write  permission  on 
the  executable  file.  Also,  if  the  executable  file  being  analyzed  is  being  run  as  another  process,  the  file  will 
be  locked  against  modifications  by  the  kernel,  and  fastbind  will  fail. 

If  the  shared  libraries  that  an  executable  is  dependent  on  are  modified  after  the  fastbind  information  is 
created,  the  dynamic  loader  will  silently  revert  to  standard  search  method  for  binding  the  symbols.  The 
fastbind  information  can  be  re-created  by  running  fastbind  on  the  executable  again,  fastbind  will 
automatically  erase  the  old  fastbind  information  and  generate  the  new  one. 

The  Id  option  +fb  can  be  used  to  instruct  the  linker  to  run  the  fastbind  tool  on  an  incomplete  executable  it 
has  produced. 

Environment  Variables 

If  did  determines  that  the  fastbind  information  is  out  of  date,  it  will  silently  revert  to  standard  search 
method  for  binding  the  symbols.  If  the  environment  variable _HP_DLDOPTS  is  set  to  -fbverbose  the 
dynamic  loader  will  emit  a  warning  message  when  the  fastbind  information  is  out  of  date. 

The  environment  variable  _HP_DLDOPTS  can  be  set  to  -nofastbind  to  make  the  dynamic  loader 
ignore  the  fastbind  information  and  revert  to  the  standard  search  method  for  binding  the  symbols. 

Options 

fastbind  recognizes  the  following  options: 

-n  Remove  the  fastbind  information  from  the  executable,  returning  it  to  the  same  state  it 

was  in  before  fastbind  was  originally  run  on  it. 

-u  Normally,  if  fastbind  detects  any  unsatisfied  symbols  while  building  the  fastbind 

information,  it  will  generate  an  error  message  and  not  modify  the  executable  file.  When 
fastbind  is  invoked  with  -u  option  however,  unresolved  symbols  are  allowed. 

EXTERNAL  INFLUENCES 
Environment  Variables 

Thefollowing  internationalization  variables  affect  the  execution  of  fastbind: 

LANG 

Determines  the  locale  category  for  native  language,  local  customs  and  coded  character  set  in  the 
absence  of  LC_ALL  and  other  LC_*  environment  variables.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of  LANG. 

LC_ALL 

Determines  the  values  for  all  locale  categories  and  has  precedence  over  LANG  and  other  LC_* 
environment  variables. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic  messages 
written  to  standard  error. 

LC_NUMERIC 

Determines  the  locale  category  for  numeric  formatting. 

LC_CTYPE 

Determines  the  locale  category  for  character  handlingfunctions. 
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NLSPATH 


Determines  the  location  of  message  catalogs  for  the  processing  of  LC_ME S SAGE S  . 

If  any  internationalization  variable  contains  an  invalid  setting,  fastbind  behaves  as  if  all  internationali- 
zation variables  are  set  toe.  See  environ  (5). 

I  n  addition,  the  foil  owing  environment  variable  affects  fastbind: 


DIAGNOSTICS 

fastbind  returns  zero  when  the  operation  is  successful.  A  non-zero  return  code  indicates  that  an  error 
occurred. 

EXAMPLES 

To  run  fastbind  on  the  executable  file  a .  out 


fastbind  a . out 

To  later  remove  the  fastbind  information  from  the  executable  file  a .  out  enter: 
fastbind  -n  a. out 

WARNINGS 

32-bit  PARISC  fastbind  does  not  work  with  EXECMAGIC  executables. 

fastbind  effectively  enforces  bind  restricted  and  bind  immediate.  For  example,  consider  an  executable 
linked  bind  deferred,  which  calls  a  function  foo()  defined  in  an  implicitly  loaded  library.  Before  the  actual 
call  is  made,  if  it  explicitly  loads  a  shared  library  (using  shl_load(3X)  with  BIND_FIRST)  having  a 
definition  for  foo(),  when  foo()  is  finally  called,  it  will  be  resolved  from  the  explicitly  loaded  library.  But  after 
running  fastbind,  the  symbol  foo()  will  be  resolved  from  the  implicitly  loaded  library. 

AUTHOR 

fastbind  was  developed  by  Hewlett-Packard. 


TMPDIR 


Specifies  a  directory  for  temporary  files  (see  tmpnam(3S)). 


enter: 


FILES 


a. out  output  file 

/usr/lib/dld .  si  32-bit  PARI  SC  dynamic  loader 

/usr/lib/pa20_64/dld.sl  64-bit  PARISC  dynamic  loader 

/usr/lib/nls/$LANG/fastbind.  cat  message  catalog 

/var/tmp/  FB*  temporary  files 


SEE  ALSO 

System  Tools: 

ld(l) 


invoke  the  link  editor 


Miscellaneous: 


a. out (4) 
dld.sl  (5) 


assembler,  compiler,  and  linker  output 
dynamic  loader 


Texts  and  Tutorials: 

HP-UX  Linker  and  Libraries  User's  Guide 
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NAME 

fastmail  -  quick  batch  mail  interface 
SYNOPSIS 

fastmail  [-b  bcc-list]  [-c  cc-list]  [-C  comments]  [-f  from-name]  [-F  from-addr]  [-i  in-reply-to] 
[-r  reply-to]  [-R  references]  [-s  subject]  filename  address-list 

DESCRIPTION 

The  fastmail  command  is  a  simple  interface  to  the  mail  system  that  allows  you  to  send  a  message 
without  the  overhead  of  an  interactive  mailer.  It  is  particularly  efficient  in  batch-processing  mail  to  very 
large  groups  of  people. 

All  addresses  should  be  full  e-mail  addresses,  sendmail  aliases  in  the  /etc/mail/aliases  file,  or 
local  login  names. 

Options 

fastmail  recognizes  the  following  options: 

-b  bcc-list  IncludeaBcc:  header  entry.  Send  blind  carbon  copies  to  the  comma-separated  list 
of  addresses  i  n  bcc-l  i  st . 

-c  cc-list  Include  a  Cc:  header  entry.  Send  carbon  copies  to  the  comma-separated  list  of 
addresses  in  cc-list. 

-C  comments  I  nclude  a  Comments  :  header  entry  with  the  string  value  comments. 

-d  Debug.  Display  information  on  processing  steps. 

-f  from-name  Replace  the  user  name  in  the  From:  header  entry  with  from-name. 

If  the  user  isx@y,  and  the  user  nameisMrX,  then  the  default  From:  lineis: 

From:    x@y  (MrX) 

The  option  -f  Joe  changes  it  to: 

From:   x@y  (Joe) 

-F  from-addr  Replace  the  address  in  the  From:  header  entry  with  from-addr.  I  n  the -f  example 
above,  — F  a@b  changes  the  original  entry  to 

From:   a@b  (MrX) 

-i  in-reply-to  I  nclude  the  In-Reply-To :  header  entry  with  the  string  value  in-reply-to.  This  is 
usually  used  to  identify  a  message  that  you  are  replying  to. 

-r  replyto  I  nclude  the  Reply-To:  header  entry  with  the  singleaddress  given  in  replyto.  This 
is  the  address  where  replies  will  usually  be  sent,  instead  of  to  the  address  given  in  the 
From:  header  entry,  very  common  with  mailing  lists. 

-R  references  I  nclude  a  References :  header  entry  containing  the  string  value  references. 

-s  subject  Include  a  Subject:  header  entry  containing  the  value  subject.  If  this  option  is 
omitted,  the  message  is  sent  without  a  subject  entry. 

Operands 

fastmail  recognizes  the  following  operands: 

address-list  A  list  of  one  or  more  blank-separated  addresses  for  the  To :  header  line.  These  are 
the  principal  recipients  of  the  message. 

filename  Either  the  name  of  a  file  containing  the  message,  or  a  dash  (-)  to  read  from  standard 
input. 

EXAMPLES 

A  Fully  Specified  Command 

This  command  has  every  option  specified. 

fastmail  \ 

-b  "bccl,bcc2,bcc3,bcc4"  \ 
-C  "Just  a  Comment"  \ 
-c  "ccl, cc2, cc3, cc4"  \ 
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-d  \ 

-F  me@anotherhost.com  \ 
-f  My  Name  \ 

-i  "Your  recent  message"  \ 
-R  REF: 13579  \ 
-r  oscar  \ 

-s  "Testing  fastmail"  \ 

message-file  \ 

addrl   addr2   addr3  addr4 

The  online  execution  displays  the  foil  owing  debug  messages: 

Mailing  to  addrl , addr2 , addr3 , addr4  ccl , cc2 , cc3 , cc4  bccl , bcc2 , bcc 
3,bcc4    [via  sendmail] 

cat  /tmp/f astmail . 5578  message-file    |    /usr/sbin/sendmail  addrl, a 
ddr2 , addr3 , addr4  ccl , cc2 , cc3 , cc4  bccl , bcc2 , bcc3, bcc4 

The  received  message  has  the  foil  owing  relevant  header  entries: 

From  realsender@mycomputer.myhost.com  Tue  Oct  22  21:14:04  EDT  1996 

Subject :    Testing  fastmail 

From:   me@anotherhost.com  (My  Name) 

Reply-To :    oscargmycomputer . myhost . com 

To:   addrl@mycomputer.myhost.com,  addr2@mycomputer.myhost.com, 

addr3@mycomputer . myhost . com,   addr4@mycomputer .myhost . com 

Cc:   ccl@mycomputer.myhost.com,  cc2@mycomputer.myhost.com, 

cc3@mycomputer . myhost . com,   cc4@mycomputer .myhost . com 

References:    REF: 1357  9 

In-Reply-To :    Your  recent  message 

Comments:    Just  a  Comment 

The  Bcc:  header  entry  is  not  transmitted. 
A  Batch  Process 

Suppose  you  are  user  big  on  machine  big-machine  and  you  have  a  shell  script  named  batch-mail 
that  contai  ns  the  fol  I  owi  ng  I  i  nes: 

# 

#  Batch  Mail  -  batch  mailing  of  a  file  to  a  LOT  of  users 
# 

#  Usage:  batch-mail   "<from>"    "<subject>"  <filename> 

sender_copy=$LOGIN 
replyto=The-Mr-Big-list 

fastmail  -b  $sender_copy  -r  $replyto  -f  "$1"  -s  "$2"   $3  personl 
sleep  10 

fastmail  -r  $replyto  -f  "$1"  -s  "$2"   $3  person2 
sleep  10 

fastmail  -r  $replyto  -f  "$1"  -s  "$2"   $3  person3 
sleep  10 

fastmail  -r  $replyto  -f  "$1"  -s  "$2"   $3  person4 
The  command: 

batch-mail    "Mr.   Big"    "Warning  to  all"  warning. text 

would  mail  a  copy  of  the  warning,  text  file  to  personl ,  person2 ,  person3,  and  person4 ,  stag- 
gered ten  seconds  apart. 

$L0GIN  would  also  silently  receive  a  copy  of  the  first  message  in  the  mail.  Each  resultant  message  would 
include  the  header  lines: 

From:   biggbig-machine   (Mr.  Big) 
Subject :   Warning  to  all 
Reply-To:  The-Mr-Big-list 
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FILES 


/etc/mail/aliases 
/usr/ sbin/ sendmail 
/tmp/f  astmail .  pid 


sendmail  aliases  file. 
Mail  transport  agent. 
Temporary  file. 


AUTHOR 

f  astmail  was  devel oped  by  HP. 

SEE  ALSO 

elm(l),  sendmail(lM). 

RFC  822  "Standard  for  the  Format  of  I  nternet  Text  Messages" 
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NAME 

file  -  determine  file  type 

SYNOPSIS 

file  [-m  mfile]  [-c  ]  [-f  ffile]  [-h]  file  ... 

DESCRIPTION 

file  performs  a  series  of  tests  on  each  file  in  an  attempt  to  classify  it.  If  file  appears  to  be  an  ASCI  I  file, 
file  examines  the  first  512  bytes  and  tries  to  guess  its  language.  If  file  is  an  executable  a. out  file, 
file  prints  the  version  stamp,  provided  it  is  greater  than  0  (see  the  description  of  the  -V  option  in  ld(l)). 

file  uses  the  file  /etc/magic  to  identify  files  that  have  some  sort  of  magic  number,  that  is,  any  file 
containing  a  numeric  or  string  constant  that  indicates  its  type.  Commentary  at  the  beginning  of 
/etc/magic  explainsthe format. 

Options 

file  recognizes  the  following  command-line  options: 
-m  mfile        Use  a  I  tern  ate  magic  file  mfile. 

-c  Check  the  magicfilefor  format  errors.  This  validation  is  not  normally  carried  out  for 

reasons  of  efficiency.  No  file  classification  is  done  when  this  option  is  specified. 

-f  ffile  Obtain  the  list  of  files  to  be  examined  from  file  ffile.    file  classifies  each  file  whose 

nameappears  in  ffile. 

-h  Do  not  follow  symbolic  links. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  file  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported.  However,  all  non-ASCII  text  files  are  identified 
as  "data". 

WARNINGS 

The  file  command  for  a  release  interprets  the  core  files  for  that  particular  release  correctly.  Using  the 
file  command  on  a  core  file  generated  on  a  different  release  will  report  incorrect  results. 

SEE  ALSO 

ld(l). 

STANDARDS  CONFORMANCE 

file:  SVI D2,  SVI D3,  XPG2,  XPG4 
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NAME 

find  -  find  files 

SYNOPSIS 

find  pathname  l i st  [expression] 

DESCRIPTION 

The  find  command  recursively  descends  the  directory  hierarchy  for  each  path  name  in  pathnamelist 
(that  is,  one  or  more  path  names)  seeking  files  that  match  a  Boolean  expression  written  in  the  primaries 
given  below.  By  default,  find  does  not  follow  symbolic  links. 

The  Boolean  expression  is  evaluated  using  short-circuit  evaluation.  This  means  that  whenever  the  result  of 
a  Boolean  operation  (AND  or  OR)  is  known  from  evaluating  the  left-hand  argument,  the  right-hand  argu- 
ment is  not  evaluated. 

I  n  the  descriptions  of  the  primaries,  the  argument  n  represents  a  decimal  integer;  +n  means  more  than  n, 
-n  means  less  than  n,  and  n  means  exactly  n. 

The  foil  owing  primaries  are  recognized: 

-depth  A  position-independent  term  which  causes  descent  of  the  directory  hierarchy  to 

be  done  so  that  all  entries  in  a  directory  are  acted  on  before  the  directory  itself. 
This  can  be  useful  when  find  is  used  with  cpio(l)  to  transfer  files  that  are  con- 
tained in  directories  without  write  permission.  It  is  also  useful  when  using 
cpio(l)  and  the  modification  dates  of  directories  must  be  preserved.  Always  true. 

-follow  A  position-independent  term  which  causes  find  to  follow  symbolic  links.  When 

following  symbolic  links,  find  keeps  track  of  the  directories  visited  so  that  it 
can  detect  infinite  loops;  for  example,  such  a  loop  would  occur  if  a  symbolic  link 
pointed  to  an  ancestor.  This  expression  should  not  be  used  with  the  -type  1 
expression.  Always  true. 

-fsonly  FStype  A  position-independent  term  which  causes  find  to  stop  descending  any  direc- 

tory whose  file  system  is  not  of  the  type  specified  by  FStype,  where  FStype  is  one 
of  cdfs,  hfs,  vxfs,  or  nfs,  representing  the  CDFS,  HFS,  J  FS  (VXFS)  or 
NFS  file  system  type,  respectively. 

I  n  this  context,  mount  points  inherit  the  FStype  of  their  parent  directory.  This 
means  that  when  -fsonly  hfs  has  been  specified  and  find  encounters  an 
NFS  mount  point  that  is  mounted  on  an  HFS  file  system,  the  mount  point  will  be 
visited  but  entries  below  that  mount  point  will  not.  It  is  important  to  note  that 
when  -fsonly  nfs  has  been  specified,  any  HFS  file  systems  that  are  beneath 
the  mount  point  of  an  NFS  file  system  are  not  traversed.  Always  true. 

True  if  the  file  physically  resides  on  the  local  system.  This  does  not  restrict  the 
search  to  only  files  which  physically  reside  on  the  local  system,  it  merely 
matches  such  files.  See  EXAMPLES. 

A  position-independent  term  that  causes  find  to  avoid  crossing  any  file  system 
mount  points  that  exist  below  starting  points  enumerated  in  pathname  list.  The 
mount  point  itself  is  visited,  but  entries  below  the  mount  point  are  not.  Always 
true. 

Identical  to  -xdev.  This  primary  is  provided  for  backward  compatibility  only, 
-xdev  is  preferred  over  -mountstop . 

True  if  file  matches  the  last  component  of  the  current  file  name.  The  matching  is 
performed  according  to  Pattern  Matching  Notation  (see  regexp(5)).  Pattern  may 
contain  supplementary  code  set  characters. 

Same  as  -name  except  the  full  path  (as  would  be  output  by  -print)  is  used 
instead  of  just  the  base  name.  Note  that  /  characters  are  not  treated  as  a  spe- 
cial case.  For  example,  */. profile  matches  .  /home/f  red/  .prof  ile. 

In  this  primary,  the  argument  mode  is  used  to  represent  file  mode  bits.  The 
argument  is  identical  in  format  to  the  mode  operand  as  described  in  chmod(l), 
with  the  exception  that  the  first  character  must  not  be  the  -  operator.  When 
using  the  symbolic  form  of  mode,  the  starting  template  is  assumed  to  have  all 
file  mode  bits  cleared. 


-local 
-xdev 

-mountstop 
-name  file 

-path  file 

-perm  [-]mode 
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-fstype  FStype 


-type  c 


-links  n 
-user  uname 


-group  gname 

-nouser 
-nogroup 
-size  n[c] 
-atime  n 

-mtime  n 
-ctime  n 


-newer  file 
-newer [tvl[tv2]]  file 


If  the  leading  minus  is  omitted,  this  primary  is  true  when  the  file  permission  bits 
exactly  match  the  value  of  mode.  Bits  associated  with  the  symbolic  attributes  s 
(set-user-ID,  set-group-ID)  and  t  (sticky  bit)  are  ignored  when  the  minus  is 
omitted. 

If  mode  is  preceded  by  a  minus,  this  primary  is  true  if  all  of  the  bits  that  are  set 
in  mode  are  also  set  in  the  file  permission  bits.  In  this  case,  the  bits  associated 
with  the  symbolic  attributes  s  andt  are  significant. 

True  if  the  file  system  to  which  the  file  belongs  is  of  type  FStype,  where  FStype 
is  one  of  cdf  s,  hf  s,  or  nf  s,  corresponding  to  the  CDFS,  HFS,  or  NFS  file  sys- 
tem type,  respectively. 

True  if  the  type  of  the  file  is  c,  where  c  is  one  of: 

■F       Rpni  ilar  filp 


f 
d 
b 


n 
M 


Regular  file 
Directory 
Block  special  file 
Character  special  file 
FIFO  (named  pipe) 
Symbolic  link 
Socket 

Network  special  file 
Mount  point 


True  if  the  file  has  n  links. 


True  if  the  file  belongs  to  the  user  uname.  If  uname  is  numeric  and  does  not 
appear  as  a  login  name  in  the  /etc/passwd  file,  it  is  taken  as  a  user  ID.  The 
uname  operand  can  be  preceded  by  a  +  or  -  to  modify  the  comparison  of  the  pri- 
maries. If  the  argument  n  represents  a  decimal  integer;  +n  means  more  than  n, 
-n  means  less  than  n,  and  n  means  exactly  n. 

True  if  the  file  belongs  to  the  group  gname.  If  gname  is  numeric  and  does  not 
appear  in  the  /etc/group  file,  it  is  taken  as  a  group  ID.  The  gname  operand 
can  be  preceded  by  a  +  or  -  to  modify  the  comparison  of  the  primaries.  If  the 
argument  n  represents  a  decimal  integer;  +n  means  more  than  n,  -n  means  less 
than  n,  and  n  means  exactly  n. 

True  if  the  file  belongs  to  a  user  I D  that  is  not  listed  in  the  password  database. 
See  passwd(4). 

True  if  the  file  belongs  to  a  group  ID  that  is  not  listed  in  the  group  database. 
Seegroup(4). 


I  f  n  i  s  fol  I  owed  by  a  c,  the 


True  if  the  file  is  n  blocks  long  (512  bytes  per  block), 
size  is  in  bytes. 

True  if  the  file  access  time  subtracted  from  the  initialized  time  is  n-1  to  n  multi- 
ples of  24  h.  The  initialization  time  shall  be  a  time  between  the  invocation  of  the 
find  utility  and  the  first  access  by  that  invocation  of  the  find  utility  to  any 
file  specified  by  its  path  operands.  The  access  time  of  directories  in 
pathnamel  i  st  is  changed  by  find  itself. 

True  if  the  file  modification  time  subtracted  from  the  initialization  time  is  n-1  to 
n  multiples  of  24  h.  The  initialization  time  shall  be  a  time  between  the  invocation 
of  the  find  utility  and  the  first  access  by  that  invocation  of  the  find  utility  to 
any  file  specified  in  its  path  operands. 

True  if  the  time  of  last  change  of  file  status  information  subtracted  from  the  ini- 
tialization time  is  n-1  to  n  multiples  of  24  h.  The  initialization  time  shall  be  a 
time  between  the  invocation  of  the  find  utility  and  the  first  access  by  that  invo- 
cation of  the  find  utilitytoany  file  specified  by  its  path  operands. 

True  if  the  current  file  has  been  modified  more  recently  than  the  argument  file. 

True  if  the  indicated  time  value  (tvl)  of  the  current  file  is  newer  than  the  indi- 
cated time  value  (tv2)  of  file.  The  time  values  tvl  and  tv2  are  each  selected  from 
the  set  of  characters: 
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a     Thetime  the  file  was  last  accessed 

c     Thetime  the  i  node  of  the  file  was  last  modified 

m     Thetime  the  file  was  last  modified 


-inum  n 


-linkedto  path 


-print 
-exec  cmd 


-ok  cmd 

-cpio  device 

-ncpio 

-prune 

-only 


(  expression  ) 


it  defaults  torn.  Note  that  the -newer  option  is 


If  thetv2  character  is  omitted, 
equivalent  to  -newermm. 

Syntax  examples; 

-newera  file 
-newermc  file 

True  if  the  file  serial  number  (inode  number)  is  n.  Note  that  file  serial  numbers 
are  unique  only  within  a  given  file  system.  Therefore,  matching  file  serial 
numbers  does  not  guarantee  that  the  referenced  files  are  the  same  unless  you 
restrict  the  search  to  a  singlefile  system. 

True  if  the  file  is  the  same  physical  file  as  the  file  specified  by  path  (i.e.,  linked  to 
path).  This  primary  is  similar  to  -inum,  but  correctly  detects  when  a  file  is 
hard-linked  to  path,  even  when  multiplefile  systems  are  searched. 

Causes  the  current  path  name  to  be  printed.  Always  true. 

True  if  the  executed  cmd  returns  a  zero  value  as  exit  status.  The  end  of  cmd 
must  be  punctuated  by  a  semicolon  (; )  or  a  plus  sign  (+)  (semicolon  and  plus  are 
special  to  the  shell  and  must  be  escaped).  When  a  plus  sign  is  used,  cmd  aggre- 
gates a  set  of  pathnames  and  executes  on  the  set.  The  reason  for  preferring  +  to 
a  semicolon  is  vastly  improved  performance.  Any  command  argument  {}  is 
replaced  by  the  current  path  name,  cmd  may  contain  supplementary  code  set 
characters. 

Same  as  -exec  except  that  the  generated  command  line  is  printed  with  a  ques- 
tion mark  first,  and  is  executed  only  if  the  user  responds  by  typing  y.  The  form 
of  the  affirmative  response  is  locale  dependent:  y  in  the  C  locale,  see  LANG  on 
environ(5).  cmd  may  contain  supplementary  code  set  characters. 

Write  the  current  file  on  device  in  cpio(4)  format  (5120-byte  records).  The  use  of 
-cpio  implies -depth.  Alwaystrue. 

Same  as  -cpio  but  adds  the  -c  option  to  cpio.  The  use  of  -ncpio  implies 
-depth.  Alwaystrue. 

If  the  current  entry  is  a  directory,  cause  find  to  skip  that  directory.  This  can 
be  useful  to  avoid  walking  certain  directories,  or  to  avoid  recursive  loops  when 
using  cpio  -p.  Note,  however,  that  -prune  is  useless  if  the  -depth  option 
has  also  been  given.  See  the  description  of  -only  and  the  EXAMPLES  section, 
below,  for  more  information.  Alwaystrue. 

This  is  a  positive-logic  version  of  -prune.  A  -prune  is  performed  after  every 
directory,  unless  -only  is  successfully  evaluated  for  that  directory.  As  an 
example,  the  following  three  commands  are  equivalent: 

find   .   -fsonly  hfs  -print 
find   .   -print  -fstype  hfs  -only 
find   .   -print    !   -fstype  hfs  -prune 

Note,  however,  that  -only  is  useless  if  the -depth  option  has  also  been  given. 
Alwaystrue. 

True  if  the  parenthesized  expression  is  true.  The  spaces  are  required. 
Parentheses  are  special  to  the  shell  and  must  be  escaped,  as  in  \  (  and  \) . 

Primaries  can  be  combined  by  using  the  foil  owing  operators  (in  order  of  decreasing  precedence): 

!  expression  Logical  NOT  operator.  True  if  expression  is  not  true. 

expression  [-a]  expression      Logical  AND  operator.  Trueif  both  of  the  expressions  are  true. 

expression  -o  expression        Logical  OR  operator.  Trueif  either  or  both  of  the  expressions  are  true. 

If  expression  is  omitted,  or  if  none  of  -print,  -ok,  -exec,  -cpio,  or  -ncpio  is  specified,  -print  is 
assumed.  The-user,  -group,  and -newer  primaries  each  evaluate  their  respective  arguments  once. 
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HFS  Access  Control  Lists 

The  -acl  primary  enables  the  user  to  search  for  HFS  access  control  list  entries.  It  is  true  if  the  file's 
access  control  list  matches  an  access  control  list  pattern  or  contains  optional  access  control  list  entries  (see 
acl  (5)).  1 1  has  three  forms: 

-acl  aclpatt  Match  all  files  whose  access  control  list  includes  all  (zero  or  more)  pattern 

entries  specified  by  the  aclpatt  pattern. 

-acl  =aclpatt  Match  a  file  only  if  its  access  control  list  includes  all  (zero  or  more)  pattern 

entries  specified  by  the  aclpatt  pattern,  and  every  entry  in  its  access  control  list 
is  matched  by  at  least  one  pattern  entry  specified  in  the  aclpatt  pattern. 

-acl  opt  Match  all  files  containing  optional  access  control  list  entries. 

The  acl  patt  stri  ng  can  be  given  as  an  operator  or  short  form  pattern;  see  acl  (5). 

By  default,  -acl  is  true  for  files  whose  access  control  lists  include  all  the  (zero  or  more)  access  control  list 
patterns  in  aclpatt.  A  file's  access  control  list  can  also  contain  unmatched  entries. 

If  aclpatt  begins  with  =,  the  remainder  of  the  string  must  match  all  entries  in  a  file's  access  control  list. 

The  aclpatt  string  (by  default,  or  the  part  following  =)  can  be  either  an  access  control  list  or  an  access  con- 
trol list  pattern.  However,  if  it  is  an  access  control  list,  aclpatt  must  include  at  least  the  three  baseentries 
((user.%,  mode),  (%.group,  mode),  and  (%.%,  mode)). 

As  a  special  case,  if  aclpatt  is  the  word  opt,  the  primary  is  true  for  files  with  access  control  list  entries. 

J  FS  Access  Control  Lists 

The  -aclv  primary  enables  the  user  to  search  for  J  FS  access  control  list  entries.  It  is  true  if  the  file's 
access  control  list  matches  an  access  control  list  pattern  or  contains  optional  access  control  list  entries  (see 
aclv(5)).  It  has  three  forms: 

-aclv  aclpatt  Match  all  files  whose  access  control  list  includes  all  (zero  or  more)  pattern 

entries  specified  by  the  aclpatt  pattern. 

-aclv  =aclpatt  Match  a  file  only  if  its  access  control  list  includes  all  (zero  or  more)  pattern 

entries  specified  by  the  aclpatt  pattern,  and  every  entry  in  its  access  control  list 
is  matched  by  at  least  one  pattern  entry  specified  in  the  aclpatt  pattern. 

-aclv  opt  Match  all  files  containing  optional  access  control  list  entries. 

By  default,  -aclv  is  true  for  files  whose  access  control  lists  includeall  the  (zero  or  more)  access  control  list 
patterns  in  aclpatt.  A  file's  access  control  list  can  also  contain  unmatched  entries. 

If  aclpatt  begins  with  =,  the  remainder  of  the  string  must  match  all  entries  in  a  file's  access  control  list. 

An  aclpatt  consists  of  a  type  field,  an  ID  field,  and  a  mode  field,  separated  by  colons.  Multiple  comma- 
separated  aclpatts  may  be  specified. 

The  type  field  is  one  of  user,  group,  class,  other  or  *,  optionally  preceded  by  default:  .  user, 
group,  class,  other  and  default  can  be  abbreviated  to  u,  g,  c,  o  and  d,  respectively.  A  type  field 
of  *  matches  any  of  the  above  types. 

The  ID  field  is  either  a  numeric  user  or  group  ID,  a  user  or  group  ID  string  from  /etc/passwd  or 
/etc/group  respectively,  or  *,  which  matches  any  I D. 

The  modefield  consists  of  a  string  of  three  characters.  The  first  character  is  either  r,  indicating  that  read 
permission  is  granted;  -,  indicating  that  read  permission  is  denied;  or  ?,  which  matches  either  state  of  read 
permission.  The  second  character  is  either  w,  -,  or  ?,  similarly  indicating  the  state  of  write  permission; 
and  the  third  character  is  either  x,  -,  or  ?,  indicating  the  state  of  execute  permission. 

As  a  special  case,  if  aclpatt  is  the  word  opt,  the  primary  is  true  for  files  with  optional  access  control  list 
entries. 

EXTERNAL  INFLUENCES 
Environment  Variables 

If  an  internationalization  variableis  not  specified  or  is  null,  it  defaults  to  the  value  of  LANG. 

If  LANG  is  not  specified  or  is  null,  it  defaults  to  C  (see  lang(5)). 

If  LC_ALL  is  set  to  a  nonempty  string  value,  it  overrides  the  values  of  all  the  other  internationalization 
variables. 
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If  any  internationalization  variable  contains  an  invalid  setting,  all  internationalization  variables  default  to 
C  (see environ (5)). 

LC_CTYPE  determines  the  interpretation  of  text  as  singleand/or  multibyte  characters,  the  classification  of 
characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expressions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

EXAMPLES 

Search  the  two  directories  /example  and  /new/example  for  files  containing  the  string  Where  are 
you  and  print  the  names  of  the  files: 

find  /example  /new/example  -exec  grep  -1  'Where  are  you'    {}  \; 

Remove  all  files  named  a .  out  or  * .  o  that  have  not  been  accessed  for  a  week: 

find  /  \(  -name  a. out  -o  -name   '*.o'    \)   -atime  +7  -exec  rm  { }  \; 

Note  that  the  spaces  delimiting  the  escaped  parentheses  are  required. 

Print  the  names  of  all  files  on  this  machine.  Avoid  walking  nfs  directories  while  still  printing  the  nfs 
mount  points: 

find  /  -fsonly  hfs  -print 

Match  only  local  files,  and  do  not  examinethe  contents  of  any  directory  found  to  be  remotely  mounted: 

find  /   !   -local  -prune  -o  -size  +50  -print 

This  only  works  correctly  if  there  are  no  local  file  systems  mounted  on  top  of  remote  directories.  This  exam- 
ple will  print  all  local  files  on  the  system  larger  than  50  blocks,  without  wasting  time  accessing  remote  files. 

To  get  the  same  effect,  but  to  check  for  files  in  local  filesystems  mounted  on  remote  directories,  use: 

find  /  -local  -size  +50  -print 

Copy  the  entire  file  system  to  a  disk  mounted  on  /Disk,  avoiding  the  recursive  copy  problem.  Both  com- 
mands are  equivalent  (note  the  use  of  -path  instead  of  -name): 

cd  / ;    find   .    !   -path   .  /Disk  -only  -print    |   cpio  -pdxm  /Disk 
cd  / ;    find   .   -path   .  /Disk  -prune  -o  -print    |   cpio  -pdxm  /Disk 

Copy  the  root  disk  to  a  disk  mounted  on  /Disk,  skipping  all  mounted  file  systems  below  /.  Note  that  - 
xdev  does  not  cause  /  to  be  skipped,  even  though  it  is  a  mount  point.  This  is  because  /  is  the  starting 
point  and  -xdev  only  affects  entries  below  starting  points. 

cd  / ;     find   .   -xdev  -print    |   cpio  -pdm  /Disk 

Change  permissions  on  all  regular  files  in  a  directory  subtree  to  mode  444,  and  permissions  on  all  direc- 
tories to  555: 

find  pathname  -type  f  -print  |  xargs  chmod  444 
find  pathname  -type  d  -print    |  xargs  chmod  555 

Note  that  output  from  find  was  piped  to  xargs(l)  instead  of  using  the  -exec  primary.  This  is 
because  when  a  large  number  of  files  or  directories  is  to  be  processed  by  a  single  command,  the  - 
exec  primary  spawns  a  separate  process  for  each  file  or  directory,  whereas  xargs  collects  file  names 
or  directory  names  into  multiple  arguments  to  a  singlechmod  command,  resulting  in  fewer  processes 
and  greater  system  efficiency.  The  +  delimiter  for  the  -exec  primary  can  be  used  to  achieve  the 
same  efficiency. 

Access  Control  List  Examples 

Find  all  files  not  owned  by  user  karl  that  have  access  control  lists  with  at  least  one  entry  associated  with 
karl,  and  one  entry  for  no  specific  user  in  group  bin  with  the  read  bit  on  and  the  write  bit  off: 

find     /     !   -user  karl  -acl   'karl.*,    %.bin+r-w'  -print 
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Find  all  files  that  have  a  read  bit  set  in  any  access  control  list  entry: 

find     /     -acl   '*.*+r'  -print 
Find  all  files  that  have  the  write  bit  unset  and  execute  bit  set  in  every  access  control  list  entry: 

find     /     -acl   ' =* . *-w+x'  -print 
Find  all  files  that  have  optional  access  control  list  entries: 

find     /     -acl  opt  -print 

DEPENDENCIES 
NFS 

The-acl  primary  is  always  false  for  NFS  files. 
WARNINGS 

Because  of  interoperability  goals,  cpio  does  not  support  archiving  files  larger  than  2GB  or  files  that  have 
user/group  IDs  larger  than  60,000  (60K).  Files  with  user/group  IDs  greater  than  60K  are  archived  and 
restored  under  the  user/group  I D  of  the  current  process. 

AUTHOR 

find  was  developed  by  AT&T  and  HP. 

FILES 

/etc/group  Group  names 

/etc/mnttab  Mount  points 

/etc/passwd  User  names 

SEE  ALSO 

chacl(l),  chmod(l),  cpio(l),  setacl(l),  sh(l),  test(l),  xargs(l),  mknod(2),  stat(2),  cpio(4),  fs(4),  group(4), 
passwd(4),  acl(5),  aclv(5),  environ(5),  lang(5),  regexp(5). 

STANDARDS  CONFORMANCE 

find:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

findmsg,  dumpmsg  -  create  message  catalog  file  for  modification 
SYNOPSIS 

findmsg  [-aiv]  [[-D  sym  ]  [-U  sym  ]]  file  ... 
dumpmsg  file  ... 

DESCRIPTION 

The  findmsg  command  extracts  messages  from  a  C  program  source  file  and  writes  them  to  the  standard 
output  in  a  format  suitablefor  input  to  gencat  (see  gencat(l)).  The  input  file  will  be  preprocessed  using 
cpp  (see  cpp(l))  in  order  to  select  print  specifiers  and  handle  ifdef ,  ifndef ...  conditional  cpp  primi- 
tives. If  multiple  input  files  are  specified  and  the  -a  option  is  not  used,  the  files  are  processed  sequentially 
such  that  message  catalog  comment  lines  identifying  the  input  file  are  written  before  the  output  for  each 
input  file. 

The  findmsg  command  scans  the  source  files  for  uncommented  lines  with  one  of  the  following  three  for- 
mats embedded  within  it: 

catgets  ( anyvar ,  NL_SETN,  n ,  <message>) 

<message>  /*  catgets  n  */ 

/*  catgets  n  */  <message> 

or  any  combination  of  these  formats  wholly  contained  on  a  single  physical  line.  <message>  could  be  a 
string  constant  or  a  combination  of  string  constants  and  print  specifiers  (PRI*).  Any  number  of  spaces  or 
tabs  can  separate  the  catgets  comment  from  the  message.  The  digit  n,  which  can  beany  valid  message 
number  (see  gencat(l)),  is  combined  with  the  message  stri ng  to  produce  a  message  catalog  source  line.  The 
message  source  line  is  assigned  to  the  set  whose  number  is  the  current  val ue  of  NL_SETN  as  set  by  the  last 
#def  ine  directive  encountered.  If  NL_SETN  has  not  yet  been  defined  when  a  message  line  is  found,  the 
message  is  output  without  a  set  number  specification.  If  more  than  one  message  is  found  belonging  to  the 
same  set  and  message  number,  the  last  message  found  is  output;  any  others  are  silently  discarded.  Condi- 
tional compilation  and  finclude  instructions  in  the  C  source  files  are  ignored. 

Options 

findmsg  recognizes  the  following  command-line  options: 

-a  Merge  identically  numbered  sets  from  multiple  input  files  so  that  gencat  can  process 

the  findmsg  output. 

-Dsym        Define  symbol  sym. 

-Usym       Cause  symbol  sym  to  be  undefined. 

-i  Consider  all  #fdefs  to  extract  messages  from  the  input  file.  Options  -D  and  -U  will  be 

used  to  select  print  specifiers  if  this  option  is  not  used. 

-v  Outputs  all  error  messages  issued  by  cpp.  By  default,  findmsg  does  not  display  the 

error  messages  issued  by  cpp. 

The  dumpmsg  command  extracts  messages  from  a  message  catalog  file  created  by  gencat .  Messages  are 
written  to  standard  output  in  a  format  suitablefor  editing  and  re-input  to  gencat . 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  messages  as  single-byte  and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set 
to  the  empty  string,  a  default  of  C  (see  lang(5)j  is  used  instead  of  LANG.  If  any  internationalization  vari- 
able contains  an  invalid  setting,  findmsg  and  dumpmsg  behave  as  if  all  internationalization  variables  are 
set  toe.  See envi ron (5). 

I  nternational  Code  Set  Support 

Single-byte  and  multi-byte  character  code  sets  are  supported. 
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WARNINGS 

The  findmsg  and  dumpmsg  commands  are  HP  proprietary,  not  portable  to  other  vendors'  systems,  and 
will  not  be  provided  in  futureHP-UX  releases. 

AUTHOR 

findmsg  and  dumpmsg  were  developed  by  HP. 

SEE  ALSO 

findstr(l),  gencat(l),  insertmsg(l),  catgets(3C). 
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NAME 

findstr  -  find  strings  for  inclusion  in  message  catalogs 

SYNOPSIS 

findstr  file  ... 

DESCRIPTION 

findstr  examines  files  of  C  source  code  for  uncommented  string  constants  which  it  places,  along  with  the 
surrounding  quotes,  on  the  standard  output,  preceding  each  by  the  file  name,  start  position,  and  length. 
This  information  is  used  by  insertmsg  (see  insertmsg(l)).  findstr  does  not  output  strings  that  are 
parameters  of  the  catgets()  routine  (see  catgets(3C)). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  comments  and  string  literals  as  single-  and/or  multi-byte  char- 
acters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  findstr  behaves  as  if  all  internationalization  variables  are  set  to 
"C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

WARNINGS 

findstr  outputs  initialization  strings  of  static  string  variables.  Calling  insertmsg  with  these  strings 
causes  their  replacement  with  a  call  to  catgets  ()  (see  catgets(3C)).  Since  the  initializer  must  be  a 
string,  this  assignment  results  in  an  invalid  C  declaration.  For  example,  the  foil  owing  line: 

static  char  *x[]  =  "message" 
is  modified  by  insertmsg  (see  insertmsg(l))  to: 

static  char  *x[]   =  (catgets (catd, NL_SETN, 1 , " message" ) ) 
These  strings  should  be  manually  removed  from  findstr  output  before  being  input  to  insertmsg. 
findstr  will  not  be  provided  in  futureHP-UX  releases. 

SEE  ALSO 

insert  msg(l). 
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NAME 

finger  -  user  information  lookup  program 

SYNOPSIS 

finger  [options]  username  ... 

DESCRIPTION 

By  default,  finger  lists  for  each  usernameon  the  system: 

•  Login  name, 

•  Full  given  name, 

•  Terminal  write  status  (if  write  permission  is  denied), 

•  I  die  time, 

•  Login  time, 

•  User's  home  directory  and  login  shell, 

•  Any  plan  the  user  has  placed  in  file  .plan  in  their  home  directory, 

•  Project  on  which  they  are  working  from  the  file  .project ,  also  in  the  home  directory, 

•  office  location  and  phone  number  (if  known), 

•  last  time  the  user  received  the  mail,  and  last  time  the  user  read  the  mail. 

Idle  time  is  in  minutes  if  listed  as  a  single  integer,  hours  and  minutes  if  a  :  is  present,  or  days  and  hours  if 
a  d  is  present.  Account  names  as  well  as  first  and  last  names  of  users  are  accepted. 

finger  can  also  be  used  to  list  users  on  a  remote  machine.  The  format  for  usernameis  user_name(3host. 
If  user  name  is  not  specified,  the  remote  system  (HP-UX  or  non-HP-UX)  uses  its  default  standard  format 
for  listing  user  information. 

Options 

finger  recognizes  the  following  options: 


-P 


-w 


-s 


-R 


-q 


-m 


-b 


-1 


-l 


-h 


-f 


Suppress  printing  the  user's  home  directory  and  shell. 

Suppress  printing  the  header  that  is  normally  printed  in  a  short-format  printout. 
Suppress  printing  the  .project  file  in  a  long-format  printout. 

Force  "idle"  output  format.  Similar  to  short  format  except  that  only  the  login  name,  termi- 
nal, login  time,  and  idletime  are  printed. 

Force  long  output  format. 

Match  arguments  only  on  user  name. 

Suppress  printing  of  the  .plan  files 

Force  quick  output  format.  Similar  to  short  format  except  that  only  the  login  name,  termi- 
nal, and  login  time  are  printed. 

Print  the  user's  host  name. 

Force  short  output  format. 

Suppress  printing  the  full  name  in  a  short-format  printout. 


WARNINGS 

Only  the  first  lineof  the  .project  file  is  printed. 


AUTHOR 


finger  was  developed  by  the  University  of  California,  Berkeley. 


FILES 


/etc/utmp  who  file 

/var/adm/wtmp  last  login  file 

/etc/passwd  for  users  names,  offices,  ... 

~/.plan  plans 

"/.project  projects 

/var/mail  mail  directory 
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SEE  ALSO 

chfn(l),  who(l). 
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NAME 

fmt  -  format  text 

SYNOPSIS 

fmt  [-cs]  [-w  width]  [file...] 

DESCRIPTION 

The  fmt  command  is  a  simple  text  formatter  that  fills  and  joins  lines  to  produce  output  lines  of  (up  to)  the 
number  of  characters  specified  in  the  -w  width  option.  The  default  width  is  72.  fmt  concatenates  the 
file  arguments.  If  none  are  given,  fmt  formats  text  from  the  standard  input. 

Blank  lines  are  preserved  in  the  output,  as  is  the  spacing  between  words,  fmt  does  not  fill  lines  beginning 
with  a  period  ( . ),  for  compatibility  with  nrof  f .  Nor  does  it  fill  lines  starting  with  From: . 

Indentation  is  preserved  in  the  output  and  input  lines  with  differing  indentation  are  not  joined  (unless  -c 
is  used). 

fmt  can  also  be  used  as  an  in-line  text  filter  for  vi;  thevi  command: 
!  }fmt 

reformats  the  text  between  the  cursor  location  and  the  end  of  the  paragraph. 
Options 

fmt  recognizes  the  following  options: 

-c  Crown  margin  mode.  Preserve  the  indentation  of  the  first  two  lines  within  a  paragraph  and 
align  the  left  margin  of  each  subsequent  line  with  that  of  the  second  line.  This  is  useful  for 
tagged  paragraphs. 

-s  Split  lines  only.  Donot  join  short  linestoform  longer  ones.  This  prevents  sample  lines  of  code, 
and  other  such  formatted  text,  from  being  unduly  combined. 

-w     Fill  output  lines  to  up  to  width  columns. 
WARNINGS 

The-w  width  option  is  acceptable  for  BSD  compatibility,  but  it  may  go  away  in  future  releases. 

SEE  ALSO 

nroff(l),  vi(l). 
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NAME 

fold  -  fold  long  lines  for  finite  width  output  device 

SYNOPSIS 

fold  [-b]  [-s]  [-w  width]  [file  ...] 

Obsolete  form: 

fold  [-s]  [-width]  [file  ...] 

DESCRIPTION 

The  fold  command  is  a  filter  that  folds  the  contents  of  the  specified  files,  breaking  the  lines  to  have  a 
maximum  of  width  column  positions  (or  bytes,  if  the  -b  option  is  specified).  The  fold  command  breaks 
lines  by  inserting  a  newline  character  so  that  each  output  line  is  the  maximum  width  possible  that  does  not 
exceed  the  specified  number  of  column  positions  (or  bytes).  A  line  cannot  be  broken  in  the  middle  of  a  char- 
acter. If  no  files  are  specified  or  if  a  file  name  of  -  is  specified,  the  standard  input  is  used. 

The  fold  command  is  often  used  to  send  text  files  to  line  printers  that  truncate,  rather  than  fold,  lines 
wider  than  the  printer  is  ableto  print. 

If  the  backspace,  tab,  or  carriage-return  characters  are  encountered  in  the  input,  and  the  -b  option  is  not 
specified,  they  are  treated  specially  as  follows: 

Backspace  The  current  count  of  line  width  is  decremented  by  one,  although  the  count  never 
becomes  negative.  Thus,  the  character  sequence  character-backspace-character 
counts  as  using  one  column  position,  assuming  both  characters  each  occupy  a  single 
column  position,  fold  does  not  insert  a  newline  character  immediately  before  or 
after  any  backspace  character. 

Tab  Each  tab  character  encountered  advances  the  column  position  pointer  to  the  next 

tab  stop.  Tab  stops  are  set  8  columns  apart  at  column  positions  1,  9, 17,  25,  33,  etc. 

Carriage-return  The  current  count  of  line  width  is  set  to  zero,  fold  does  not  insert  a  newline 
character  immediately  before  or  after  any  carriage-return  character. 

Note  that  fold  may  affect  any  underliningthat  is  present. 
Options 

The  fold  command  recognizes  the  following  options  and  command-line  arguments: 
-b  Count  width  in  bytes  rather  than  in  column  positions. 

-s  Break  the  line  on  the  last  blank  character  found  before  the  specified  number  of 

column  positions  (or  bytes).  If  none  are  found,  break  the  line  at  the  specified  line 
length. 

-w  width  Specify  the  maximum  line  length,  in  column  positions  (or  bytes  if  -b  is  specified), 

-width  The  default  value  is  80.  width  should  be  a  multiple  of  8  if  tabs  are  present,  or  the 

tabs  should  be  expanded  using  expand  before  processing  by  fold  (see  expand(l)). 

The -width  option  is  obsolescent  and  may  be  removed  in  a  future  release. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single- and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set 
to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  fold  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 
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SEE  ALSO 

expand(l). 

STANDARDS  CONFORMANCE 

fold:  XPG4,  P0SIX.2 
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NAME 

forder  -  convert  file  data  order 

SYNOPSIS 

forder  [-a]  [-1]  [-n]  [file  ...] 

DESCRIPTION 

The  text  orientation  (mode)  of  a  file  can  be  right-to-left  (non-Latin)  or  left-to-right  (Latin).  This  text  orien- 
tation can  affect  the  way  data  is  arranged  in  the  file.  The  data  arrangements  that  result  are  called  screen 
order  and  keyboard  order,  forder  converts  the  order  of  characters  in  the  file  from  screen  order  to  key- 
board order  or  vice  versa. 

forder  reads  the  concatenation  of  input  files  (or  standard  input  if  none  are  given)  and  produces  on  stan- 
dard output  a  converted  version  of  its  input.  If  -  appears  as  an  input  file  name,  forder  reads  standard 
input  at  that  point  (use  —  to  delimit  the  end  of  options  in  such  instances). 

forder  converts  input  files  for  all  languages  that  are  read  from  right-to-left.  Unless  the  -a  option  is 
used,  the  command  merely  copies  input  files  to  standard  output  for  languages  that  are  read  from  left-to- 
right. 

Options 

forder  recognizes  the  following  options: 

-a    Convert  file  data  order  for  languages  read  from  left-to-right. 
-1    Identify  thefileas  having  been  created  in  Latin  mode, 
-n    Identify  thefileas  having  been  created  in  non-Latin  mode. 

EXTERNAL  INFLUENCES 
Environment  Variables 

The  LANGOPTS  environment  variable  determines  the  mode  and  order  of  the  file.  The  syntax  of  LAN- 
GOPTS  is: 

[mode]  [  order  ] 

where  mode  describes  the  mode  of  a  file:  1  represents  Latin  mode,  and  n  represents  non-Latin  mode. 
Non-Latin  mode  is  assumed  for  values  other  than  landn.  The  order  describes  the  data  order  of  a  file:  k 
is  keyboard,  and  sis  screen.  Keyboard  order  is  assumed  for  values  other  than  k  and  s.  M  ode  i  nforma- 
tion  in  LANGOPTS  can  be  overridden  from  the  command  line. 

The  LC_ALL  environment  variable  determines  the  direction  of  a  language  (left-to-right  or  right-to-left). 
The  LC_NUMERIC  environment  variabledetermines  whether  a  language  has  alternative  numbers. 
The  LANG  environment  variabledetermines  the  languagein  which  messages  are  displayed. 

I  nternational  Code  Set  Support 

Si  ngle-byte  character  code  sets  are  supported. 

EXAMPLES 

Thefollowing  command  begins  with  fil el,  which  exists  in  screen  order,  converts  it  to  keyboard  order,  sorts 
the  keyboard-ordered  output,  converts  it  back  to  screen  order,  and  redirects  the  output  to  file2.  Note  that 
-n  is  given  to  inform  forder  that  fil  el  was  created  in  non-Latin  mode. 

forder  -n  filel    |    sort    |   forder  -n  >  file2 
WARNINGS 

It  is  the  user's  responsibility  to  ensure  that  the  LANGOPTS  environment  variable  accurately  reflects  the 
status  of  the  file. 

If  present,  alternative  numbers  always  have  a  left-to-right  orientation. 

The  forder  command  is  HP  proprietary,  not  portableto  other  vendors'  systems,  and  will  not  be  provided 
in  future  HP-UX  releases. 

AUTHOR 

forder  was  developed  by  HP. 
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SEE  ALSO 

environ(5),  strord(3C),  nljust(l). 
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NAME 

from  -  who  is  my  mail  from? 

SYNOPSIS 

from  [-s  sender]  [user] 

DESCRIPTION 

from  prints  the  mail  header  lines  in  your  mailbox  file  to  show  who  sent  you  mail.  If  user  is  specified, 
user's  mailbox  is  examined  instead  of  your  own.  If  the  -s  option  is  given,  only  headers  of  mail  from  sender 
are  printed. 

EXAMPLES 

List  header  lines  for  all  current  mail  in  your  mailbox  that  was  sent  by  ken. 
from  -s  ken 

FILES 

/var/mail/* 

AUTHOR 

from  was  developed  by  the  University  of  California,  Berkeley. 

SEE  ALSO 

biff(l),  mail(l),  prmail(l). 
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NAME 

fruled  -  turn  on/off  attention  LEDs  (cell,  cabinet  and  I/O  chassis  attention  LEDs) 

SYNOPSIS 

fruled  [-f | -o]  [-B]  -c  cell  [-c...] 

fruled  [-f | -o]  [-B]  -i  l/Ochassis  [-i...] 

fruled  [-f|-o]  -b  cabinet  [-b...] 

fruled  [-f]  -C  [-1  cabinet]  [-1...] 

fruled  [-f]  -I  [-1  cabinet]  [-1...] 

DESCRIPTION 

The  fruled  command  turns  on/off  attention  LEDs  of  cells  or  I/O  chassis.  The  command  can  also  be  used 
to  start  or  stop  flashing  cabinet  number  LEDs. 

If  a  cell  attention  LED  is  being  illuminated,  the  cabinet  number  LED  of  the  cabinet  that  contains  the  com- 
ponent can  be  made  to  flash  by  using  the  -B  option.  Likewise,  if  an  internal  component's  LED  is  being 
turned  off,  the  cabinet  number  LED  can  also  be  made  to  stop  flashing  using  the -B  option. 

Options  and  Arguments 

fruled  recognizes  the  following  command  line  options  and  arguments: 

-f  Turn  off  specified  attention  LED(s).  This  is  the  default. 

The-f  and  -o  options  are  mutually  exclusive, 
-o  Turn  on  specified  attention  LED(s). 

The-o  option  is  unavailablewith  -C  or  -I. 

-B  Start  or  stop  flashing  the  cabinet  number  LED  of  the  cabinet  that  contains  the  cell  or  I/O 

chassis. 

The-B  option  is  only  availablewith  -c  and  -i. 

-c  cell  Turn  on/off  the  specified  cell  attention  LED. 

cell  can  be  specified  either  in  the  local  (cabinet#slot#)  or  global  (cellJD)  format.  For 
example,  the  cell  located  in  cabinet  2,  slot  4  is  locally  identified  as  2/4  or  globally  as  simply 
20. 

-i  l/Ochassis   Turn  on/off  the  specified  I  /  Ochassis  attention  LED. 

An  1/  Ochassis  can  be  specified  in  the  form  of  cabinet^enclosure^chassis#.  For  example, 
the  I/O  chassis  located  in  cabinet  1,  enclosure  4  and  I/O  chassis  slot  1  is  identified  as  1/4/1. 

-b  cabinet        Start  or  stop  flashing  the  cabinet  number  LED  of  the  specified  cabinet. 

-C  Turn  off  all  cell  attention  LEDs. 

By  default  the  scope  will  be  the  whole  complex  if  -1  option  is  not  specified. 
-I  Turn  off  all  I/O  chassis  LEDs. 

By  default  the  scope  will  be  the  entire  complex  if  the  -1  option  is  not  specified. 
-1  cabinet        Limit  the  scope  of  the -C  or  -I  option  toa  given  cabinet. 

EXIT  STATUS 

Thefruled  utility  exits  with  one  of  the  foil  owing  values: 

0  Successful  completion. 

1  Error  condition  occurred. 

2  No  LED  associated  with  specified  object. 

EXAMPLES 

Turn  on  the  attention  LED  of  the  cell  located  in  cabinet  0  slot  4  and  also  turn  on  the  attention  LED  of  the 
cabinet  in  which  it  is  contained. 
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f ruled  -o  -B  -c  0/4 

Turn  off  the  attention  LEDs  of  2  cells  located  in  cabinet  0,  slot  4  and  cabinet  0,  slot  6. 
fruled  -f  -c  0/4  -c  0/6 
WARNINGS 

The  presence  of  ?  in  the  command  output  indicates  a  problem  in  address  translation.  If  you  see  ?  (exam- 
ple: "I/O  chassis  0/?/3")  in  the  command  output,  pi  ease  contact  your  Hewlett  Packard  representative. 

AUTHOR 

fruled  was  developed  by  the  Hewlett-Packard  Company. 
SEE  ALSO 

parstatus(l),  partition(l),  frupower(lM):  parcreate(lM),  parmodify(llv|):  parremove(lM):  parunlock(lM). 


HP-UX  Release  Hi:  December  2000 


-2- 


Section  1-289 


ftio(l) 


ftio(l) 


NAME 

ftio-  faster  tape  I/O 

SYNOPSIS 

ftio  -ol-O  [achpvxAELM]  [-B  blksize]  [-D  type]  [-e  extarg]  [-K  comment]  [-L  filelist] 
[-N  datefile]  [-S  script]  [-T  tty]  [-Z  nobufs]  tapedev  [pathnames]  [-F  ignorenames] 

ftio  — ±  I  —I  [cdfmptuvxAEMPR]  [-B  blksize]  [-S  script]  [-T  tty]  [-Z  nobufs]  tapedev  [patterns] 

ftio  -g  [v]  tapedev  [patterns] 

DESCRIPTION 

ftio  is  a  tool  designed  specifically  for  copying  files  to  tape  drives.  It  performs  faster  than  either  cpio  or 
tar  in  comparable  situations  (see  cpio(l)  and  tar(l)).  ftio  uses  multiple  processes  (to  read/write  the  file 
system  and  to  write/read  the  tape  device),  with  large  amounts  of  memory  sharing  between  processes  as 
well  as  a  large  block  size  for  reading  and  writing  to  the  tape. 

ftio  is  compatible  with  cpio  in  that  output  from  cpio  is  always  readable  by  ftio,  and  output  from 
ftio  is  readable  by  cpio,  except  as  explained  in  the  "cpio  Compatibility"  section,  later  in  the  manpage. 

ftio  must  be  invoked  with  exactly  one  of  the  following  options:  -o,  -O,  -i,  -I,  or  -g.  The-o  and  -O 
options  specify  that  ftio  is  writing  "out"  from  file  system  to  tape;  the  -i  and  -I  options  specify  that 
ftio  is  writing  "in"  from  tape  to  file  system.  The-o,  -O,  -i,  and -I  options  can  be  followed  by  modifiers 
that  must  appear  immediately  after  the  option  with  no  spaces  between  the  option  and  the  modifier,  as  in 
ftio  -idxE  (see  Modifiers  section  below). 

tapedev  specifies  the  name  of  a  device  special  file  for  the  tape  device  to  which  the  output  is  written.  A  dev- 
ice on  a  remote  machine  can  be  specified  in  the  form 

machine:  device_special_file 

ftio  creates  a  server  process  from  /usr/sbin/rmt  on  the  remote  machine  to  access  the  tape  device. 
If  /usr/sbin/rmt  does  not  exist  on  the  remote  system,  ftio  creates  a  server  process  from 
/etc/rmt,  on  the  remote  machine  to  access  the  tape  device. 

Options 

ftio  recognizes  the  following  options: 

-o  Copy  (out)  files  from  the  file  system  to  tapedev,  including  path  name  and  status  infor- 

mation. If  pathnames  are  specified,  ftio  recursively  descends  pathnames  looking 
for  files,  and  copies  those  files  to  tapedev.  If  pathnames  are  not  specified,  ftio 
reads  the  standard  input  to  obtain  a  list  of  path  names  to  copy,  ftio  can  copy  to 
multipletapes  if  required.  For  every  tape  used,  ftio  generates  a  tape  header  con- 
taining the  current  tape  volume  number,  machine  node  name  and  type,  operating  sys- 
tem name,  release  and  version  numbers  (all  from  the  uname()  system  call;  see 
uname(2)),  username  of  the  person  issuingthe  ftio  command,  the  time  and  date  the 
command  was  executed,  the  number  of  consecutive  times  the  current  media  has  been 
used,  a  comment  field,  and  other  items  used  internally  by  ftio.  The  tape  header  is 
separated  from  the  main  body  of  the  tape  archive  by  an  end-of-file  mark.  The  tape 
header  can  be  read  by  invoking  cat  with  the  device  file  name  as  the  first  argument 
(see  cat(l)).  Note,  character  and  block  device  special  files  written  with  the  -o  option 
are  not  transportable  to  other  hp-ux  implementations. 

-O  Copy  out  files  in  the  same  way  as  ftio  -ocva,  when  no  modifiers  are  used  with  the 

-O.  However,  if  the  .  ftiorc  file  exists  in  the  user's  home  directory,  ftio  opens 
this  file  and  scans  for  lines  preceded  by  0=.  Options  defined  on  matching  lines  are 
passed  to  ftio  as  if  they  had  been  specified  on  the  command  line.  See  examples 
section. 

-i  Extract  (copy  into  the  file  system)  files  from  tapedev,  which  is  assumed  to  be  a  tape 

and  the  product  of  a  previous  ftio  -o  operation.  Only  files  with  names  that  match 
patterns,  according  to  the  rules  of  Pattern  Matching  Notation  (see  regexp(5)),  are 
selected.  In  addition,  a  leading  !  within  a  pattern  indicates  that  only  those  names 
that  do  not  match  the  remainder  of  the  pattern  should  be  selected.  Multiple  patterns 
can  be  specified.  If  no  patterns  are  specified,  the  default  for  patterns  is  *  (that  is, 
select  all  files).  The  extracted  files  are  conditionally  created  and  copied  into  the 
current  directory  tree,  based  upon  the  options  described  below.  The  permissions  of 
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the  files  are  those  of  the  previous  -o  operation. 

-I  Extract  (copy  into  the  file  system)  files  in  the  same  way  as  for  ftio  -icdmv,  when 

no  modifiers  are  used  with  the -I.  However,  ifthe  .  ftiorc  file  exists  in  the  user's 
home  directory,  ftio  opens  this  file,  and  scans  for  lines  preceded  by  l=.  Options 
defined  on  matching  lines  are  passed  to  ftio  as  if  they  had  been  specified  on  the 
command  line.  See  examples  section. 

-g  Read  the  file  list  in  tapedev.  If  patterns  is  specified,  only  file  names  that  match  are 

printed.  Note  that  file  names  are  always  preceded  by  the  volume  that  ftio 
expected  the  file  to  be  on  when  the  file  list  was  created;  thus  only  the  last  volume  is 
valid  in  this  respect. 

-e  extarg  Specifies  the  handling  of  any  extent  attributes  of  the  file[s]  to  be  archived.  Extent 
attributes  cannot  be  preserved  when  archiving  files  with  ftio.  extarg  takes  one  of 
the  foil  owing  values: 

warn  Issue  a  warning  message  and  archive  the  file  without  extent  attri- 
butes. 

ignore  A  file  with  extent  attributes  will  be  archived,  without  preserving  the 
extent  attributes  and  without  issuinga  warning  message. 

force  A  file  with  extent  attributes  will  not  be  archived  and  a  warning  mes- 
sage will  beissued. 

If  -e  isnot  specified,  the  default  value  for  extarg  iswarn. 

-B  blksize  Specify  the  size  (in  bytes)  of  blocks  written  to  tape.  This  number  can  end  with  k, 
which  specifies  multiplication  by  1024.  The  use  of  larger  blocks  generally  improves 
performance  and  tape  usage.  The  maximum  allowable  block  size  is  limited  by  the 
tape  drive  used.  A  default  of  16384  bytes  is  set  because  this  is  the  maximum  block 
size  on  most  Hewlett-Packard  tape  drives. 

-D  type  Descend  a  directory  recursively,  only  if  the  file  system  to  which  it  belongs  is  type, 
where  type  can  behfs,  vxfs,  or  nfs. 

-F  ignorenames 

Arguments  following  — F  specify  patterns  that  should  not  be  copied  to  the  tape.  The 
same  rules  apply  to  ignorenames  as  to  patterns;  see  the  earlier  description  for  ftio 


-K  comment    Specify  a  comment  to  be  placed  in  the  ftio  tape  header. 


-L  filelist 


-M 


-R 


-S  script 


-T  tty 


Create  a  list  of  the  files  being  backed  up.  filelist  specifies  the  output  file.  If  path- 
names is  specified,  perform  the  file  search  and  generate  a  list  of  files  prior  to  actually 
commencing  the  backup.  This  list  is  then  appended  to  the  tape  header  of  each  tape  in 
the  backup  as  a  list  of  files  that  ftio  attempted  to  fit  onto  this  tape.  The  last  tape 
in  the  backup  contains  a  catalog  identifying  where  the  files  are  in  the  archive  set.  If 
pathnames  is  not  also  specified,  the  file  list  is  taken  from  standard  input  before  the 
backup  begins.  In  addition  to  generating  file  lists,  the  -L  option  implements  tape 
checkpointing,  allowing  the  backup  to  restart  from  a  write  failure  on  bad  media. 

Make  fully  compatible  with  cpio.  That  is,  do  not  generate  or  expect  tape  headers 
and  change  the  default  block  size  to  5120  bytes.  (See  the  cpio  Compatibility  section 
below.) 


-N  datefile      Only  files  newer  than  the  file  specified  in  datefileare  copied  totape. 


Resynchronize automatically,  when  ftio  goes  out  of  phase.  This  is  useful  when  res- 
toring from  a  multi-tape  backup  from  tapes  other  than  the  first.  By  default,  ftio 
asks  the  user  if  resynchronization  is  required. 

Specify  a  command  to  be  invoked  every  time  a  tape  is  completed  in  a  multi-tape 
backup.  The  command  is  invoked  by  the  Bourne  shell  (see  sh-bourne(l)  with  the  fol- 
lowing arguments:  script  tapeno  username.  script  is  the  string  argument  script 
specified  with  the  -S  option,  tape  no  is  the  number  of  the  tape  required,  and 
usernameisthe  user  who  invoked  ftio.  Typically,  the  string  script  specifies  a  shell 
script  which  is  used  to  notify  the  user  that  a  tape  change  is  required. 


Specify  alternative  to  /dev/tty. 
terminal  interaction  is  required. 


Normally  /dev/tty  is  opened  by  ftio  when 
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-Z  nobufs  Specify  the  number  of  blksize chunks  of  memory  to  use  as  buffer  space  between  the 
two  processes,  where  blksizeis  the  size  of  blocks  written  to  the  tape.  More  chunks  is 
usually  better,  but  a  point  is  reached  where  no  improvement  is  gained,  and  perfor- 
mance might  deteriorate  as  buffer  space  is  swapped  out  of  main  memory.  A  default 
value  of  16  is  set  for  nobufs,  but  using  32  or  64  might  improve  performance  if  your 
system  is  not  heavily  loaded.  Best  results  are  obtained  when  backups  are  performed 
with  the  system  in  single-user  mode  (see  shutdown (1M)). 

Modifiers 

Thefollowing  modifiers  can  be  used  with  certain  options  as  indicated  in  the  SYNOPSIS: 

a  After  files  are  copied  to  tape,  reset  their  access  time  to  appear  as  though  the  files  were  not 
accessed  by  ftio. 

c         Write  header  information  i n  ASCI  I  character  form,  for  portability. 

d         When  restoring  files,  create  directories  as  needed. 

f         Copy  in  all  files  except  those  that  match  patterns. 

h  Archive  the  files  to  which  symbolic  links  point,  as  if  they  were  normal  files  or  directories.  By 
default,  ftio  archives  the  link  itself. 

m  Retain  previous  file  modification  time  and  ownership  of  file.  Restoring  modification  time  does 
not  apply  to  directories  that  are  being  restored. 

p  At  the  end  of  the  backup,  print  the  number  of  blocks  transferred,  the  total  time  taken 
(excluding  tape  rewind  and  reel -change  time),  and  the  effective  transfer  rate  calculated  from 
these  figures.  These  values  are  printed  at  the  end  of  each  tape  if  p  is  specified  twice. 

t         Print  only  a  tableof  contents  of  the  input.  No  files  are  created,  read,  or  copied. 

u  Copy  unconditionally  (by  default,  ftio  does  not  replace  a  newer  file  with  a  older  file  of  the 
same  name). 

v  Beverbose.  Print  a  list  of  file  names  and  tape  headers.  When  used  with  the  t  modifier,  the 
tableof  contents  looks  the  same  as  the  output  of  the  Is  -1  (ell)  command  (see  I s(l)). 

x  Save  or  restore  device  special  files,  ftio  uses  mknod(2)  to  recreate  these  files  during  a 
restore  operation.  Thus,  this  modifier  is  restricted  to  users  with  appropriate  privileges.  This 
is  intended  for  intrasystem  (backup)  use.  Restoring  device  files  onto  a  different  system  can  be 
very  dangerous. 

A  If  copying  from  tape  (-i  or  -I  option),  print  all  file  names  found  on  the  tape  archive,  noting 
which  files  have  been  restored.  This  is  useful  when  the  user  restores  selected  files,  but  wants 
to  know  which  (if  any)  files  are  on  the  tape. 

If  copying  to  tape  (-o  or  -O  option),  the  A  modifier  suppresses  warning  messages  regarding 
optional  access  control  list  entries,  ftio(l)  does  not  back  up  optional  access  control  list  entries 
in  a  file's  access  control  list  (see  acl  (5)).  Normally,  a  warning  message  is  printed  for  each  file 
that  has  optional  access  control  list  entries. 

E  When  archiving,  store  all  files  having  absolute  path  names  (that  is,  path  names  beginning 
with  /)  with  path  names  relative  to  the  root  directory  (in  other  words,  remove  the  leading  /). 
On  restoration,  any  files  in  the  archive  that  had  an  absolute  path  name  before  archiving  are 
restored  relative  to  the  current  directory. 

L  Same  as  the  -L  option,  except  that  the  file  list  is  left  in  the  current  directory  as  the  file 
ftio .  list ,  instead  of  the  file  named  in  filelist. 

P  On  restoration,  use  prealloc  ()  to  allocate  disk  space  beforehand  for  the  file  (see  preal- 
loc(2)).  This  vastly  improves  the  localization  of  file  fragments. 

When  end-of-tape  is  reached,  ftio  invokes  script  if  the  -S  option  was  specified,  rewinds  the  current 
tape,  then  asks  the  user  to  mount  the  next  tape. 

To  pass  one  or  more  metacharacters  to  ftio  without  having  the  shell  expand  them,  protect  them  either 
by  preceding  each  of  them  with  a  backslash  (as  in  /usr\*),  or  enclosing  them  in  protective  singlequotes 
(as  in  '  /usr*'  ). 
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cpio  Compatibility 

ftio  uses  the  same  archive  format  as  cpio.  However,  by  default  ftio  creates  tape  headers  and  uses  a 
tape  block  size  of  16KB,  cpio  by  default  uses  512-byte  blocks.  When  used  with  the  -B  option,  cpio 
uses  5120  byte  blocks.  To  achieve  full  compatibility  with  cpio  in  either  input  or  output  mode,  the  user 
should  specify  the  M  modifier,  ftio  -oM  creates  a  single-  or  multi-tape  archive  that  has  no  tape 
headers,  and,  by  default,  the  same  block  size  as  cpio  -[o|i]B.  An  archive  created  by  a  cpio  -oB 
command  can  be  restored  using  ftio  -iM.  If  the  M  modifier  of  ftio  is  combined  with  a  -B  512 
block-size  specification,  full  compatibility  with  cpio  -[o  I  i]  (no  -B)  is  achieved. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  pattern  matching  notation  for  file 
name  generation. 

LC_CTYPE  determines  the  characters  matched  by  character  class  expressions  in  pattern  matching  nota- 
tion. 

LC_TIME  determines  the  format  and  contents  of  date  and  time  strings. 
LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_COLLATE,  LC_CTYPE,  or  LC_TIME  is  not  specified  in  the  environment  or  is  set  to  the  empty 
string,  the  value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not 
specified  or  is  set  to  the  empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of  LANG.  If  any  interna- 
tionalization variable  contains  an  invalid  setting,  ftio  behaves  as  if  all  internationalization  variables  are 
set  to  C.  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-byte  character  code  sets  are  supported. 

EXAMPLES 

Copy  the  entire  contents  of  the  file  system  (including  special  files)  onto  tape  drive 
/dev/rmt/cOtOdOBEST: 

ftio  -ox  /dev/rmt/cOtOdOBEST  / 

Restore  all  the  files  on  /dev/rmt/cOtOdOBEST,  relative  to  the  current  directory: 

ftio  -idxE  /dev/rmt/cOtOdOBEST 

List  the  contents  of  a  backup  set  created  using  ftio  -o.  Note  that  use  of  the  v  modifier  gives  a  more 
detailed  listing,  and  displays  the  contents  of  tape  headers. 

ftio  -itv  /dev/rmt/cOtOdOBEST 

Show  how  to  use  the  .  ftiorc  file: 

Assume  a  .  ftiorc  file  exists  in  the  user's  home  directory  and  contains  the  foil  owing: 

#  Sample   .ftiorc  file. 

1=  cdmuvEpp  -B  16k  -S  /usr/local/bin/ftio . change 
0=  cavEpp  -Z  8  -B  16k  -S  /usr/local/bin/f tio . change 

I  nvoke  ftio  with  the  following  command  line  to  back  up  the  user's  home  directory  and  the  operat- 
ing system  commands  directory: 

ftio  -O  /dev/rmt/cOtOdOBEST  /home/my _home  /usr/sbin 

Specifying  the  -o  option  causes  ftio  to  check  the  .ftiorc  file  for  additional  options.  In  this 
case,  character  headers  are  generated,  access  times  are  reset,  a  listing  of  the  files  copied  are  printed 
to  standard  output,  all  file  names  are  copied  to  /dev/rmt/cOtOdOBEST  with  path  names  relative 
to  /,  performance  data  is  printed  when  the  backup  is  complete  (and  at  every  tape  change),  and,  if  the 
backup  goes  beyond  one  media  the  script,  /usr/local/bin/ftio  .  change  is  invoked  by  ftio 
after  each  media  is  completed. 

WARNINGS 

Because  of  industry  standardsand  interoperability  goals,  ftio  does  not  support  the  archival  of  files  larger 
than  2GB  or  files  that  have  user/group  I  Ds  greater  than  60K.  Files  with  user/group  I  Ds  greater  than  60K 
are  archived  and  restored  under  the  user/group  I D  of  the  current  process. 
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ftio  operates  using  System  V  shared  memory  and  semaphores.  The  resources  committed  to  these  func- 
tions are  not  freed  automatically  by  the  system  when  the  process  terminates,  ftio  does  this  only  when 
it  terminates  normally,  or  when  it  terminates  after  receiving  one  the  foil  owing  signals:  SIGHUP,  SIGINT, 
SIGTERM.  Any  other  signal  is  handled  in  the  default  manner  described  by  signal (2).  Note  that  the 
behavior  for  SIGKILL  is  to  terminate  the  process  without  delay.  Thus,  if  ftio  receives  a  SIGKILL 
signal  (as  might  be  produced  by  the  indiscriminate  use  of  kill  -9  (see  kill(l)),  system  resources  used  for 
shared  memory  and  semaphores  are  not  returned  to  the  system.  If  it  becomes  necessary  to  terminate  an 
invocation  of  ftio,  use  kill  -15  instead.  Current  system  usage  of  shared  memory  and  semaphores 
can  be  checked  using  the  ipcs  command  (see  ipcs(l)).  Committed  resources  can  be  removed  using 
ipcrm  (see  ipcrm(l)). 

AUTHOR 

ftio  was  developed  by  H  P. 

SEE  ALSO 

cpio(l),  find(l),  ipcs(l),  ipcrm(l),  kill(l),  ls(l),  rmt(lM),  mknod(2),  prealloc(2),  signal(2),  uname(2),  acl(5), 
environ(5),  lang(5),  regexp(5),  mt(7). 
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NAME 

ftp  -  file  transfer  program 

SYNOPSIS 

ftp  l-g]  [-i]  [-n]  [-c]  [-v]  [-B  size]  [server-host  ] 
DESCRIPTION 

ftp  isa  user  interface  to  the  File  Transfer  Protocol,  ftp  copies  files  over  a  network  connection  between 
the  local  "client"  host  and  a  remote  "server"  host,    ftp  runs  on  the  client  host. 

Options 

The  ftp  command  supports  the  foil  owing  options: 

-g  Disablefile  name  "globbing";  seethe  glob  command,  below.  By  default,  when  this  option  is  not 
specified,  globbing  is  enabled. 

-i  Disable  interactive  prompting  by  multiple-file  commands;  see  the  prompt  command,  below. 
By  default,  when  this  option  is  not  specified,  prompting  is  enabled. 

-n  Disable  "auto-login";  see  the  open  command,  below.  By  default,  when  this  option  is  not 
specified,  auto-login  is  enabled. 

-c  When  this  option  is  set,  the  SYST  and  TYPE  calls  are  not  made  by  the  ftp  client  to  the 
server  upon  establishing  a  connection.  The  -c  option  takes  effect  only  when  auto-login  is  dis- 
abled i.e.  when  it  is  invoked  along  with  the  -n  option.  This  option  does  not  disablethe  SYST 
and  TYPE  commands,  but  only  refrains  from  invoking  these  commands  upon  establishinga  con- 
nection. 

-v  Enable  verbose  output;  see  the  verbose  command,  below.  If  this  option  is  not  specified,  ftp 
displays  verbose  output  only  if  the  standard  input  is  associated  with  a  terminal. 

-B  Set  the  buffer  size  of  the  data  socket  to  size  blocks  of  1024  bytes.  The  valid  range  for  size  is  an 
integer  from  1  to  64  (default  is  56). 

Note:  A  large  buffer  size  will  improve  the  performance  of  ftp  on  fast  links  (e.g.,  FDDI),  but 
may  cause  long  connection  times  on  slow  links  (e.g.,  X.25). 

The  name  of  the  server  host  that  ftp  communicates  with  can  be  specified  on  the  command  line.  If  the 
server  host  is  specified,  ftp  immediately  opens  a  connection  to  the  server  host;  see  the  open  command, 
below.  Otherwise,  ftp  waits  for  commands  from  the  user. 

File  Transfer  Protocol  specifies  file  transfer  parameters  for  type,  mode,  form,  and  struct,  ftp  supports 
the  ASCII,  binary,  and  tenex  File  Transfer  Protocol  types.  ASCII  is  the  default  FTP  type.  (It 
should  be  noted  though  that,  whenever  ftp  establishes  a  connection  between  two  similar  systems,  it 
switches  automatically  to  the  more  efficient  binary  type.)  ftp  supports  only  the  default  values  for  the 
file  transfer  parameters  mode  which  defaults  to  stream,  form  which  defaults  to  non-print ,  and  struct 
which  defaults  to  file. 

COMMANDS 

ftp  supports  the  following  commands.  Command  arguments  with  embedded  spaces  must  be  enclosed  in 
quotes  (for  example,  "argument  with  embedded  spaces"). 

! [command  [args]] 

Invoke  a  shell  on  the  local  host.  The  SHELL  environment  variable  specifies  which  shell  program  to 
invoke,  ftp  invokes  /usr/bin/sh  if  SHELL  is  undefined.  If  command  is  specified,  the  shell 
executes  it  and  returns  to  ftp.  Otherwise,  an  interactive  shell  is  invoked.  When  the  shell  ter- 
minates, it  returns  to  ftp. 

$  macro-name  [args] 

Execute  the  macro  macro-name  that  was  defined  with  the  macdef  command.  Arguments  are 
passed  to  the  macro  unglobbed. 

account  [passwd] 

Supply  a  supplemental  password  required  by  a  remote  system  for  access  to  resources  once  a  login  has 
been  successfully  completed.  If  no  argument  is  included,  the  user  is  prompted  for  an  account  pass- 
word in  a  non-echoing  input  mode. 

append  I  oca  I -file  [remote-file] 

Copy  local-file  to  the  end  of  remote-file.  If  remote-file  is  left  unspecified,  the  local  file  name  is  used  in 
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naming  the  remote  file  after  being  altered  by  any  ntrans  or  nmap  setting, 
ascii 

Set  the  file  transfer  type  to  network  ASCI  I .  This  is  the  default  type, 
bell 

Sound  a  bell  after  each  filetransfer  completes, 
binary 

Set  the  file  transfer  type  to  binary. 

bye  Close  the  connection  to  the  server  host  if  a  connection  was  open,  and  exit.  Typing  an  end-of-file  (EOF) 
character  also  terminates  and  exits  the  session. 

case 

Toggle  remote  computer  file  name  case  mapping  during  mget  commands.  When  case  is  on  (the 
default  is  off),  remote  computer  file  names  with  all  letters  in  uppercase  are  written  in  the  local  direc- 
tory with  the  letters  mapped  to  lowercase. 

cd  remote-directory 

Set  the  working  directory  on  the  server  host  to  remote-directory. 

cdup 

Set  the  working  directory  on  the  server  host  to  the  parent  of  the  current  remote  working  directory. 

chmod  mode  file-name 

Change  the  permission  modes  of  the  file  file-name  on  the  remote  system  to  mode. 

close 

Terminate  the  connection  to  the  server  host.  The  close  command  does  not  exit  ftp.  Any  defined 
macros  are  erased. 

cr  Toggle  carriage  return  stripping  during  ascii  type  file  retrieval.  Records  are  denoted  by  a 
carriage-return/line-feed  sequence  during  ascii  type  file  transfer.  When  cr  is  on  (the  default), 
carriage  returns  are  stripped  from  this  sequence  to  conform  with  the  UNIX  single  line-feed  record  del- 
imiter. Records  on  non-UNIX  remote  systems  may  contain  single  line-feeds;  when  an  ascii  type 
transfer  is  made,  these  line-feeds  can  be  distinguished  from  a  record  delimiter  only  when  cr  is  off. 

delete  remote-file 

Delete  remote-file.  The  remote- file  can  bean  empty  directory.  No  globbing  is  done. 

dir  [remote-directory]  [local -file] 

Write  a  remote-directory  listing  to  standard  output  or  optionally  to  local-file.  If  neither  remote- 
directory  nor  local-file  is  specified,  list  the  remote  working  directory  to  standard  output.  If  interactive 
prompting  is  on,  ftp  prompts  the  user  to  verify  that  the  last  argument  is  indeed  the  target  file  for 
dir  output.  Globbing  characters  are  always  expanded. 

disconnect 

A  synonym  for  close. 

form  format 

Set  the  file  transfer  form  to  format.  The  only  supported  format  is  non-print 

get  remote-file  [local -file] 

Copy  remote-file  to  local-file.  If  local-file  is  unspecified,  ftp  uses  the  specified  remote-file  name  as 
the  local -file  name,  subject  to  alteration  by  the  current  case,  ntrans,  and  nmap  settings. 

glob 

Toggle  file  name  globbing.  When  file  name  globbing  is  enabled,  ftp  expands  csh(l)  metacharacters 
in  file  and  directory  names.  These  characters  are  *,  ?,  [,  ],  ",  {,  and  }.  The  server  host  expands 
remote  file  and  directory  names.  Globbing  metacharacters  are  always  expanded  for  the  Is  and  dir 
commands.  If  globbing  is  enabled,  metacharacters  are  also  expanded  for  the  multiple-file  commands 
mdelete,  mdir,  mget,  mis,  andmput. 

hash 

Toggle  printing  of  a  hash-sign  (#)  for  each  1024  bytes  transferred.  Note  that  the  use  of  this  feature 
may  cause  performance  degradation. 

help  [command] 

Print  an  informative  message  about  the  ftp  command  called  ftp-command.  If  ftp-command  is 
unspecified,  print  a  list  of  all  ftp  commands. 
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idle  [seconds] 

Set  the  inactivity  timer  on  the  remote  server  to  seconds  seconds.  If  seconds  is  omitted,  ftp  prints 
the  current  inactivity  timer. 

led  [local -directory] 

Set  the  local  working  directory  to  local -directory.  If  local -directory  is  unspecified,  set  the  local  work- 
ing directory  to  the  user's  local  home  directory. 

Is  [remote-directory]  [local -file] 

Write  a  listing  of  remote-directory  to  local-file.  The  listing  includes  any  system-dependent  information 
that  the  server  chooses  to  include;  for  example,  most  UNIX  systems  produce  output  from  the  com- 
mand Is  -1  (see  also nlist).  If  neither  remote-directory  nor  local-file  is  specified,  list  the  remote 
working  directory.  If  globbing  is  enabled,  globbing  metacharacters  are  expanded. 

macdef  macro-name 

Define  a  macro.  Subsequent  lines  are  stored  as  the  macro  macro-name;  an  empty  input  line  ter- 
minates macro  input  mode.  There  is  a  limit  of  16  macros  and  4096 total  characters  in  all  defined  mac- 
ros. Macros  remain  defined  until  a  close  command  is  executed.  The  macro  processor  interprets  $ 
and  \  as  special  characters.  A  $  followed  by  a  number  (or  numbers)  is  replaced  by  the  corresponding 
argument  on  the  macro  invocation  command  line.  A  $  followed  by  an  i  signalsto  the  macro  processor 
that  the  executing  macro  is  to  be  looped.  On  the  first  pass  $i  is  replaced  by  the  first  argument  on  the 
macro  invocation  command  line,  on  the  second  pass  it  is  replaced  by  the  second  argument,  and  so  on. 
A  \  followed  by  any  character  is  replaced  by  that  character.  Use  the  \  to  prevent  special  treatment 
of  the$. 

mdelete  [remote-files] 

Delete  remote- files.  If  globbing  is  enabled,  globbing  metacharacters  are  expanded. 

mdir  remote-files  local -file 

Write  a  listing  of  remote-files  to  local-file.  If  globbing  is  enabled,  globbing  metacharacters  are 
expanded.  If  interactive  prompting  is  on,  ftp  prompts  the  user  to  verify  that  the  last  argument  is 
indeed  the  target  local  file  for  mdir  output. 

mget  remote-files 

Copy  remote-files  to  the  local  system.  If  globbing  is  enabled,  globbing  metacharacters  are  expanded. 
The  resulting  local  file  names  are  processed  according  to  case,  ntrans,  and  nmap  settings. 

mkdir  directory-name 

Create  remote  directory-name. 

mis  remote-files  I  oca  I -file 

Write  an  abbreviated  listing  of  remote-files  to  local-file.  If  globbing  is  enabled,  globbing  metacharac- 
ters are  expanded.  If  interactive  prompting  is  on,  ftp  prompts  the  user  to  verify  that  the  last  argu- 
ment is  indeed  the  target  local  file  for  mis  output. 

mode  [mode-name] 

Set  the  FTP  filetransfer  modeto  mode-name.  Theonly  supported  mode  is  stream. 

modtime  remote-file 

Show  the  last  modification  time  of  remote- file. 

mput  I  oca  I -files 

Copy  local -files  from  the  local  system  to  the  remote  system.  The  remote  files  have  the  same  name  as 
the  local  files  processed  according  to  ntrans  and  nmap  settings.  If  globbing  is  enabled,  globbing  char- 
acters are  expanded. 

newer  file-name 

Get  the  file  only  if  the  modification  time  of  the  remote  file  is  more  recent  that  the  file  on  the  current 
system.  If  the  file  does  not  exist  on  the  current  system,  the  remote  file  is  considered  newer.  Other- 
wise, this  command  is  identical  to  get. 

nlist  [remote-directory]  [local -file] 

Write  an  abbreviated  listing  of  remote-directory  to  local-file.  If  remote-directory  is  left  unspecified,  the 
current  working  directory  is  used.  If  interactive  prompting  is  on,  ftp  prompts  the  user  to  verify 
that  the  last  argument  is  indeed  the  target  local  filefor  nlist  output. 

nmap  [inpattern  outpattern] 

Set  or  unset  the  filename  mapping  mechanism.  If  no  arguments  are  specified,  the  filename  mapping 
mechanism  is  unset.   If  arguments  are  specified,  remote  filenames  are  mapped  during  mput 
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commands  and  put  commands  issued  without  a  specified  remote  target  filename.  If  arguments  are 
specified,  local  filenames  are  mapped  during  mget  commands  and  get  commands  issued  without  a 
specified  local  target  filename.  This  command  is  useful  when  connecting  to  a  non-UNIX  remote  com- 
puter with  different  file  naming  conventions  or  practices.  The  mapping  follows  the  pattern  set  by 
inpattern  and  outpattern.  inpattern  is  a  template  for  incoming  filenames  (which  may  have  already 
been  processed  according  to  the  ntrans  and  case  settings).  Variable  tempi ating  is  accomplished 

by  including  the  sequences  $1,  $2        $9  in  inpattern.  Use  \  to  prevent  this  special  treatment  of 

the  $  character.  All  other  characters  are  treated  literally,  and  are  used  to  determine  the  nmap 
inpattern  variable  values.  For  example,  given  inpattern  $1.$2  and  the  remote  file  name 
my  data,  data,  $1  would  have  the  value  mydata,  and  $2  would  have  the  value  data.  Theout- 

pattern  determines  the  resulting  mapped  filename.  The  sequences  $1,  $2         $9  are  replaced  by 

any  value  resulting  from  the  inpattern  template.  The  sequence  $0  is  replaced  by  the  original 
filename.  Additionally,  the  sequence  [seql,  seq2]  is  replaced  by  seql  if  seql  is  not  a  null  string;  oth- 
erwise it  is  replaced  by  seq2.  For  example,  the  command  nmap  $1.$2.$3 
[$1,  $2]  .  [$2,  file]  would  yield  the  output  filename  myfile.data  for  input  filenames 
myfile.data  and  myfile  . data .  old,  myf ile  .  f ile  for  the  input  filename  myfile,  and 
myf ile  .myf ile  for  the  input  filename  .myfile.  Spaces  can  be  included  in  outpattern,  as  in  the 
example:  nmap  $1  |  sed  s/*$//  >  $1  Use  the  \  character  to  prevent  special  treatment  of  the 
$,  [,  ] ,  and  ,  characters. 

ntrans  [inchars  [outchars]] 

Set  or  unset  the  filename  character  translation  mechanism.  If  no  arguments  are  specified,  the 
filename  character  translation  mechanism  is  unset.  If  arguments  are  specified,  characters  in  remote 
filenames  are  translated  during  mput  commands  and  put  commands  issued  without  a  specified 
remote  target  filename.  If  arguments  are  specified,  characters  in  local  filenames  are  translated  dur- 
ing mget  commands  and  get  commands  issued  without  a  specified  local  target  filename.  This  com- 
mand is  useful  when  connecting  to  a  non-UNIX  remote  computer  with  different  file  naming  conven- 
tions or  practices.  Characters  in  a  filename  matching  a  character  in  inchars  are  replaced  with  the 
corresponding  character  in  outchars.  If  the  character's  position  in  inchars  is  longer  than  the  length  of 
outchars,  the  character  is  deleted  from  the  file  name. 

open  server-host  [port-number] 

Establish  a  connection  to  server-host,  using  port-number  (if  specified).  If  auto-login  is  enabled,  ftp 
attempts  to  log  into  the  server  host. 

passive 

Toggle  passive  mode  of  transfer.  By  default,  the  passive  mode  of  transfer  is  disabled.  This  command 
enables  the  server  to  specify  the  data  port  for  the  ftp  transfer. 

prompt 

Toggle  interactive  prompting.  By  default,  ftp  prompts  the  user  for  a  yes  or  no  response  for  each 
output  file  during  multiple-file  commands.  If  interactive  prompting  is  disabled,  ftp  performs  the 
command  for  all  specified  files. 

proxy  ftp-command 

Execute  an  ftp  command  on  a  secondary  control  connection.  This  command  allows  simultaneous 
connection  to  two  remote  FTP  servers  for  transferring  files  between  the  two  servers.  The  first 
proxy  command  should  be  an  open,  to  establish  the  secondary  control  connection.  Enter  the  com- 
mand proxy  ?  to  see  other  FTP  commands  executable  on  the  secondary  connection.  Thefollowing 
commands  behave  differently  when  prefaced  by  proxy:  open  does  not  define  new  macros  during 
the  auto-login  process,  close  does  not  erase  existing  macro  definitions,  get  and  mget  transfer 
files  from  the  host  on  the  primary  control  connection  to  the  host  on  the  secondary  control  connection, 
and  put,  mput,  and  append  transfer  files  from  the  host  on  the  secondary  control  connection  to  the 
host  on  the  primary  control  connection.  Third  party  file  transfers  depend  upon  support  of  the  FTP 
protocol  PASV  command  by  the  server  on  the  secondary  control  connection. 

put  I  oca  I -file  [remote-file] 

Copy  local -file  to  remote- file.  If  remote- file  is  unspecified,  ftp  assigns  the  local -file  name,  processed 
according  to  any  ntrans  or  nmap  settings,  to  the  remote-filename. 

pwd  Write  the  name  of  the  remote  working  directory  to  stdout. 

quit 

A  synonym  for  bye. 

quote  arguments 

Send  arguments,  verbatim,  to  the  server  host.  Seeftpd(lM). 
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recv  remote-file  [local -file] 
A  synonym  for  get. 

reget  remote-file  [local -file] 

reget  acts  like  get,  except  that  if  local-file  exists  and  is  smaller  than  remote-file,  local-file  is 
presumed  to  be  a  partially  transferred  copy  of  remote-file  and  the  transfer  is  continued  from  the 
apparent  point  of  failure.  This  command  is  useful  when  transferring  very  large  files  over  networks 
that  tend  to  drop  connections. 

rhelp  [command-name] 

Request  help  from  the  server  host.  If  command-name  is  specified,  supply  it  to  the  server.  See 
ftpd(lM). 

rstatus  [file-name] 

With  no  arguments,  show  status  of  remote  machine.  If  file-name  is  specified,  show  status  of  file-name 
on  remote  machine. 

rename  remote-from  remote-to 

Rename  remote-from,  which  can  be  either  a  file  or  a  directory,  to  remote-to. 

reset 

Clear  reply  queue.  This  command  re-synchronizes  command/reply  sequencing  with  the  remote  FTP 
server.  Resynchronization  may  be  necessary  following  a  violation  of  the  FTP  protocol  by  the  remote 
server. 

restart  marker 

Restart  the  immediately  following  get  or  put  at  the  indicated  marker.  On  UNIX  systems,  marker 
isusuallya  byte  offset  into  the  file. 

rmdir  remote-directory 

Delete  remote-directory,  remote-directory  must  bean  empty  directory. 

runique 

Toggle  storing  of  files  on  the  local  system  with  unique  filenames.  If  a  file  already  exists  with  a  name 
equal  to  the  target  local  filename  for  a  get  or  mget  command,  a  .1  is  appended  to  the  name.  If 
the  resulting  name  matches  another  existing  file,  a  .2  is  appended  to  the  original  name.  I f  this  pro- 
cess continues  up  to  .  99,  an  error  message  is  printed,  and  the  transfer  does  not  take  place,  ftp 
reports  the  unique  filename.  Note  that  runique  does  not  affect  local  files  generated  from  a  shell 
command  (seebelow).  The  default  value  is  off. 

send  local -file  [remote-file] 
A  synonym  for  put . 

sendport 

Toggle  the  use  of  PORT  commands.  By  default,  ftp  attempts  to  use  a  PORT  command  when  estab- 
lishing a  connection  for  each  data  transfer.  If  the  PORT  command  fails,  ftp  uses  the  default  data 
port.  When  the  use  of  PORT  commands  is  disabled,  ftp  makes  no  attempt  to  use  PORT  commands 
for  each  data  transfer.  This  is  useful  for  certain  FTP  implementations  that  ignore  PORT  commands 
but  (incorrectly)  indicate  that  they've  been  accepted.  See  ftpd(lM).  Turning  sendport  off  may 
cause  delays  in  the  execution  of  commands. 

site  arguments 

Send  arguments,  verbatim,  to  the  server  host  as  a  SITE  command.  Seeftpd(livi). 

size  remote-file 

Show  the  size  of  remotefile. 

status 

Show  the  current  status  of  ftp. 

struct  [struct-name] 

Set  the  FTP  file  transfer  struct  to  struct-name.  The  only  supported  struct  is  file. 

sunique 

Toggle  storing  of  files  on  remote  machine  under  unique  file  names.  The  remote  server  reports  the 
uniquename.  By  default,  sunique  is  off. 

system 

Show  the  type  of  operating  system  running  on  the  remote  machine. 
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tenex 

Set  the  FTP  filetransfer  typeto  tenex. 
type  [type-name] 

Set  the  FTP  file  transfer  type  to  type-name.  If  type-name  is  unspecified,  write  the  current  type  to 
stdout.  Ascii,  binary,  and  tenex  are  the  types  currently  supported. 

umask  [newmask] 

Set  the  default  umask  on  the  remote  server  to  newmask.  If  newmask  is  omitted,  the  current  umask  is 
printed. 

user  user-name  [password ]  [account] 

Log  into  the  server  host  on  the  current  connection,  which  must  already  be  open.  A  .netrc  file  in 
the  user's  local  home  directory  can  provide  the  user-name,  password,  and  optionally  the  account;  see 
netrc(4).  Otherwise  ftp  prompts  the  user  for  this  information.  The  HP-UX  FTP  server  does  not 
require  an  account.  For  security  reasons,  ftp  always  requires  a  password.  It  does  not  log  into 
remote  accounts  that  do  not  have  a  password. 

verbose 

Toggle  verbose  output.  If  verbose  output  is  enabled,  ftp  displays  responses  from  the  server  host, 
and  when  a  filetransfer  completes  it  reports  statistics  regarding  the  efficiency  of  the  transfer. 

?  [command] 

A  synonym  for  the  help  command.  Prints  the  help  information  for  the  specified  command. 

Aborting  A  File  Transfer 

To  abort  a  file  transfer,  use  the  terminal  interrupt  key  (usually  Ctrl-C).  Sending  transfers  are  halted 
immediately,  ftp  halts  incoming  (receive)  transfers  by  first  sending  a  FTP  protocol  ABOR  command  to 
the  remote  server,  then  discarding  any  further  received  data.  The  speed  at  which  this  is  accomplished 
depends  upon  the  remote  server's  support  for  ABOR  processing.  If  the  remote  server  does  not  support  the 
ABOR  command,  an  ftp>  prompt  does  not  appear  until  the  remote  server  completes  sending  the 
requested  file. 

The  terminal  interrupt  key  sequence  is  ignored  while  ftp  awaits  a  reply  from  the  remote  server.  A  long 
delay  in  this  mode  may  result  from  the  ABOR  processing  described  above,  or  from  unexpected  behavior  by 
the  remote  server,  including  violations  of  the  FTP  protocol.  If  the  delay  results  from  unexpected  remote 
server  behavior,  the  local  ftp  program  must  be  killed  manually. 

File  Naming  Conventions 

Files  specified  as  arguments  to  ftp  commands  are  processed  according  to  the  foil  owing  rules. 

•  If  the  file  name  -  is  specified,  ftp  uses  the  standard  input  (for  reading)  or  standard  output  (for  writ- 
ing). 

•  If  the  first  character  of  the  file  name  is  | ,  ftp  interprets  the  remainder  of  the  argument  as  a  shell 
command,  ftp  forks  a  shell,  using  popen()  (see  popen(3S))  with  the  supplied  argument,  and  reads 
(writes)  from  standard  output  (standard  input).  If  the  shell  command  includes  spaces,  the  argument 
must  be  quoted,  as  in: 

"I   Is  -It". 

Some  useful  examples  of  this  mechanism  are: 

Is   .    "|   more" . 
The  above  command  lists  the  files  in  the  current  directory  page  by  page. 

put     "I   tail  -20  loc_file"  rem_file. 
This  command  copies  the  last  twenty  lines  of  the  local  file  "loc  file"  to  the  remote  system  as  "rem  file". 

•  Otherwise,  if  globbing  is  enabled,  ftp  expands  local  file  names  according  to  the  rules  used  by  the  C 
shell  (see  csh(l));  see  the  glob  command,  below.  If  the  ftp  command  expects  a  single  local  file  (e.g., 
put),  only  the  first  filename  generated  by  the  globbing  operation  is  used. 

•  For  mget  commands  and  get  commands  with  unspecified  local  file  names,  the  local  filename  is  named 
the  same  as  the  remote  filename,  which  may  be  altered  by  a  case,  ntrans,  or  nmap  setting.  The 
resulting  filename  may  then  be  altered  if  runique  ison. 

•  For  mput  commands  and  put  commands  with  unspecified  remote  file  names,  the  remote  filename  is 
named  the  same  as  the  local  filename,  which  may  be  altered  by  a  ntrans  or  nmap  setting.  The 
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resulting  filename  may  then  be  altered  by  the  remote  server  if  sunique  is  on. 
WARNINGS 

Correct  execution  of  many  commands  depends  upon  proper  behavior  by  the  remote  server. 
DIAGNOSTICS 

Error!    could  not  retrieve  authentication  type. 

Please  notify  sys  admin. 

There  are  two  authentication  mechanisms  used  by  ftp.  One  authentication  mechanism  is  based  on 
Kerberos  and  the  other  is  not.  The  type  of  authentication  mechanism  is  obtained  from  a  system  file 
which  is  updated  by  inetsvcs_sec  (see  inetsvcs  sec(lM)).  If  the  system  file  does  not  contain 
known  authentication  types,  the  above  error  is  displayed. 

AUTHOR 

ftp  was  developed  by  the  University  of  California,  Berkeley. 
SEE  ALSO 

csh(l),  rcp(l),  ftpd(lM),  inetsvcssec(lM),  netrc(4),  ftpusers(4),  hosts(4). 
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NAME 

ftp  -  file  transfer  program 

SYNOPSIS 

ftp  [-g]  [-i]  [-n]  [-c]  [-P]  [-v]  [-B  size]  [server-hcst  ] 
DESCRIPTION 

ftp  isa  user  interface  to  the  File  Transfer  Protocol,  ftp  copies  files  over  a  network  connection  between 
the  local  "client"  host  and  a  remote  "server"  host,    ftp  runs  on  the  client  host. 

Options 

The  ftp  command  supports  the  foil  owing  options: 

-g  Disablefile  name  "globbing";  seethe  glob  command,  below.  By  default,  when  this  option  is  not 
specified,  globbing  is  enabled. 

-i  Disable  interactive  prompting  by  multiple-file  commands;  see  the  prompt  command,  below. 
By  default,  when  this  option  is  not  specified,  prompting  is  enabled. 

-P  Disables  Kerberos  authentication  and  authorization.  Only  applicable  in  a  secure  environment 
based  on  Kerberos  V5.  When  this  option  is  specified,  a  password  is  required  and  the  password  is 
sent  across  the  network  in  a  readableform.  By  default,  if  this  option  is  not  specified,  a  password 
is  not  required  and  Kerberos  authentication  and  authorization  takes  place  instead.  See  sis(5). 

-n  Disable  "auto-login";  see  the  open  command,  below.  By  default,  when  this  option  is  not 
specified,  auto-login  is  enabled. 

-c  When  this  option  is  set,  the  SYST  and  TYPE  calls  are  not  made  by  the  ftp  client  to  the 
server  upon  establishing  a  connection.  The  -c  option  takes  effect  only  when  auto-login  is  dis- 
abled i.e.  when  it  is  invoked  along  with  the  -n  option.  This  option  does  not  disablethe  SYST 
and  TYPE  commands,  but  only  refrains  from  invoking  these  commands  upon  establishinga  con- 
nection. 

-v  Enable  verbose  output;  see  the  verbose  command,  below.  If  this  option  is  not  specified,  ftp 
displays  verbose  output  only  if  the  standard  input  is  associated  with  a  terminal. 

-B  Set  the  buffer  size  of  the  data  socket  to  size  blocks  of  1024  bytes.  The  valid  range  for  size  is  an 
integer  from  1  to  64  (default  is  56). 

Note:  A  large  buffer  size  will  improve  the  performance  of  ftp  on  fast  links  (e.g.,  FDDI),  but 
may  cause  long  connection  times  on  slow  links  (e.g.,  X.25). 

The  name  of  the  server  host  that  ftp  communicates  with  can  be  specified  on  the  command  line.  If  the 
server  host  is  specified,  ftp  immediately  opens  a  connection  to  the  server  host;  see  the  open  command, 
below.  Otherwise,  ftp  waits  for  commands  from  the  user. 

File  Transfer  Protocol  specifies  file  transfer  parameters  for  type,  mode,  form,  and  struct,  ftp  supports 
the  ASCII,  binary,  and  tenex  File  Transfer  Protocol  types.  ASCII  is  the  default  FTP  type.  (It 
should  be  noted  though  that,  whenever  ftp  establishes  a  connection  between  two  similar  systems,  it 
switches  automatically  to  the  more  efficient  binary  type.)  ftp  supports  only  the  default  values  for  the 
file  transfer  parameters  mode  which  defaults  to  stream,  form  which  defaults  to  non-print ,  and  struct 
which  defaults  to  file. 

COMMANDS 

ftp  supports  the  following  commands.  Command  arguments  with  embedded  spaces  must  be  enclosed  in 
quotes  (for  example,  "argument  with  embedded  spaces"). 

! [command  [args]] 

Invoke  a  shell  on  the  local  host.  The  SHELL  environment  variable  specifies  which  shell  program  to 
invoke,  ftp  invokes  /usr/bin/sh  if  SHELL  is  undefined.  If  command  is  specified,  the  shell 
executes  it  and  returns  to  ftp.  Otherwise,  an  interactive  shell  is  invoked.  When  the  shell  ter- 
minates, it  returns  to  ftp. 

$  macro-name  [args] 

Execute  the  macro  macro-name  that  was  defined  with  the  macdef  command.  Arguments  are 
passed  to  the  macro  unglobbed. 

account  [passwd] 

Supply  a  supplemental  password  required  by  a  remote  system  for  access  to  resources  once  a  login  has 
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been  successfully  completed.  If  no  argument  is  included,  the  user  is  prompted  for  an  account  pass- 
word in  a  non-echoing  input  mode. 

append  I  oca  I -file  [remote-file] 

Copy  local-file  to  the  end  of  remote-file.  If  remote-file  is  left  unspecified,  the  local  file  name  is  used  in 
naming  the  remote  file  after  being  altered  by  any  ntrans  or  nmap  setting. 

ascii 

Set  the  file  transfer  type  to  network  ASCI  I .  This  is  the  default  type, 
bell 

Sound  a  bell  after  each  filetransfer  completes, 
binary 

Set  the  file  transfer  type  to  binary. 

bye  Close  the  connection  to  the  server  host  if  a  connection  was  open,  and  exit.  Typing  an  end-of-file  (EOF) 
character  also  terminates  and  exits  the  session. 

case 

Toggle  remote  computer  file  name  case  mapping  during  mget  commands.  When  case  is  on  (the 
default  is  off),  remote  computer  file  names  with  all  letters  in  uppercase  are  written  in  the  local  direc- 
tory with  the  letters  mapped  to  lowercase. 

cd  remote-directory 

Set  the  working  directory  on  the  server  host  to  remote-directory. 

cdup 

Set  the  working  directory  on  the  server  host  to  the  parent  of  the  current  remote  working  directory. 

chmod  mode  file-name 

Change  the  permission  modes  of  the  file  file-name  on  the  remote  system  to  mode. 

close 

Terminate  the  connection  to  the  server  host.  The  close  command  does  not  exit  ftp.  Any  defined 
macros  are  erased. 

cr  Toggle  carriage  return  stripping  during  ascii  type  file  retrieval.  Records  are  denoted  by  a 
carriage-return/line-feed  sequence  during  ascii  type  file  transfer.  When  cr  is  on  (the  default), 
carriage  returns  are  stripped  from  this  sequence  to  conform  with  the  UNIX  single  line-feed  record  del- 
imiter. Records  on  non-UNIX  remote  systems  may  contain  single  line-feeds;  when  an  ascii  type 
transfer  is  made,  these  line-feeds  can  be  distinguished  from  a  record  delimiter  only  when  cr  is  off. 

delete  remote-file 

Delete  remote-file.  The  remote- file  can  bean  empty  directory.  No  globbing  is  done. 

dir  [remote-directory]  [local -file] 

Write  a  remote-directory  listing  to  standard  output  or  optionally  to  local-file.  If  neither  remote- 
directory  nor  local-file  is  specified,  list  the  remote  working  directory  to  standard  output.  If  interactive 
prompting  is  on,  ftp  prompts  the  user  to  verify  that  the  last  argument  is  indeed  the  target  file  for 
dir  output.  Globbing  characters  are  always  expanded. 

disconnect 

A  synonym  for  close. 

form  format 

Set  the  file  transfer  form  to  format.  The  only  supported  format  is  non-print 

get  remote-file  [local -file] 

Copy  remote-file  to  local-file.  If  local-file  is  unspecified,  ftp  uses  the  specified  remote-file  name  as 
the  local -file  name,  subject  to  alteration  by  the  current  case,  ntrans,  and  nmap  settings. 

glob 

Toggle  file  name  globbing.  When  file  name  globbing  is  enabled,  ftp  expands  csh(l)  metacharacters 
in  file  and  directory  names.  These  characters  are  *,  ?,  [,  ],  ",  {,  and  }.  The  server  host  expands 
remote  file  and  directory  names.  Globbing  metacharacters  are  always  expanded  for  the  Is  and  dir 
commands.  If  globbing  is  enabled,  metacharacters  are  also  expanded  for  the  multiple-file  commands 
mdelete,  mdir,  mget, mis,  and mput . 

hash 

Toggle  printing  of  a  hash-sign  (#)  for  each  1024  bytes  transferred.  Note  that  the  use  of  this  feature 
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may  cause  performance  degradation, 
help  [command] 

Print  an  informative  message  about  the  ftp  command  called  ftp-command.  If  ftp-command  is 
unspecified,  print  a  list  of  all  ftp  commands. 

idle  [seconds] 

Set  the  inactivity  timer  on  the  remote  server  to  seconds  seconds.  If  seconds  is  omitted,  ftp  prints 
the  current  inactivity  timer. 

led  [local -directory] 

Set  the  local  working  directory  to  local -directory.  If  local -directory  is  unspecified,  set  the  local  work- 
ing directory  to  the  user's  local  home  directory. 

Is  [remote-directory]  [local -file] 

Write  a  listing  of  remote-directory  to  local-file.  The  listing  includes  any  system-dependent  information 
that  the  server  chooses  to  include;  for  example,  most  UNIX  systems  produce  output  from  the  com- 
mand Is  -1  (see  also nlist).  If  neither  remote-directory  nor  local-file  is  specified,  list  the  remote 
working  directory.  If  globbing  is  enabled,  globbing  metacharacters  are  expanded. 

macdef  macro-name 

Define  a  macro.  Subsequent  lines  are  stored  as  the  macro  macro-name;  an  empty  input  line  ter- 
minates macro  input  mode.  There  is  a  limit  of  16  macros  and  4096 total  characters  in  all  defined  mac- 
ros. Macros  remain  defined  until  a  close  command  is  executed.  The  macro  processor  interprets  $ 
and  \  as  special  characters.  A  $  followed  by  a  number  (or  numbers)  is  replaced  by  the  corresponding 
argument  on  the  macro  invocation  command  line.  A  $  followed  by  an  i  signalsto  the  macro  processor 
that  the  executing  macro  is  to  be  looped.  On  the  first  pass  $i  is  replaced  by  the  first  argument  on  the 
macro  invocation  command  line,  on  the  second  pass  it  is  replaced  by  the  second  argument,  and  so  on. 
A  \  followed  by  any  character  is  replaced  by  that  character.  Use  the  \  to  prevent  special  treatment 
of  the$. 

mdelete  [remote-files] 

Delete  remote- files.  If  globbing  is  enabled,  globbing  metacharacters  are  expanded. 

mdir  remote-files  local -file 

Write  a  listing  of  remote-files  to  local-file.  If  globbing  is  enabled,  globbing  metacharacters  are 
expanded.  If  interactive  prompting  is  on,  ftp  prompts  the  user  to  verify  that  the  last  argument  is 
indeed  the  target  local  file  for  mdir  output. 

mget  remote-files 

Copy  remote-files  to  the  local  system.  If  globbing  is  enabled,  globbing  metacharacters  are  expanded. 
The  resulting  local  file  names  are  processed  according  to  case,  ntrans,  and  nmap  settings. 

mkdir  directory-name 

Create  remote  directory-name. 

mis  remote-files  I  oca  I -file 

Write  an  abbreviated  listing  of  remote-files  to  local-file.  If  globbing  is  enabled,  globbing  metacharac- 
ters are  expanded.  If  interactive  prompting  is  on,  ftp  prompts  the  user  to  verify  that  the  last  argu- 
ment is  indeed  the  target  local  file  for  mis  output. 

mode  [mode-name] 

Set  the  FTP  filetransfer  modeto  mode-name.  Theonly  supported  mode  is  stream. 

modtime  remote-file 

Show  the  last  modification  time  of  remote- file. 

mput  I  oca  I -files 

Copy  local -files  from  the  local  system  to  the  remote  system.  The  remote  files  have  the  same  name  as 
the  local  files  processed  according  to  ntrans  and  nmap  settings.  If  globbing  is  enabled,  globbing  char- 
acters are  expanded. 

newer  file-name 

Get  the  file  only  if  the  modification  time  of  the  remote  file  is  more  recent  that  the  file  on  the  current 
system.  If  the  file  does  not  exist  on  the  current  system,  the  remote  file  is  considered  newer.  Other- 
wise, this  command  is  identical  to  get. 

nlist  [remote-directory]  [local -file] 

Write  an  abbreviated  listing  of  remote-directory  to  local-file.  If  remote-directory  is  left  unspecified,  the 
current  working  directory  is  used.  If  interactive  prompting  is  on,  ftp  prompts  the  user  to  verify 


Section  1-304 


-3- 


HP-UX  Release  Hi:  December  2000 


ftp(l) 


Kerberos 


ftp(l) 


that  the  last  argument  is  indeed  the  target  local  filefor  nlist  output. 

nmap  [inpattern  outpattern] 

Set  or  unset  the  filename  mapping  mechanism.  If  no  arguments  are  specified,  the  filename  mapping 
mechanism  is  unset.  If  arguments  are  specified,  remote  filenames  are  mapped  during  mput  com- 
mands and  put  commands  issued  without  a  specified  remote  target  filename.  If  arguments  are 
specified,  local  filenames  are  mapped  during  mget  commands  and  get  commands  issued  without  a 
specified  local  target  filename.  This  command  is  useful  when  connecting  to  a  non-UNIX  remote  com- 
puter with  different  file  naming  conventions  or  practices.  The  mapping  follows  the  pattern  set  by 
inpattern  and  outpattern.  inpattern  is  a  template  for  incoming  filenames  (which  may  have  already 
been  processed  according  to  the  ntrans  and  case  settings).  Variable  tempi ating  is  accomplished 

by  including  the  sequences  $1,  $2        $9  in  inpattern.  Use  \  to  prevent  this  special  treatment  of 

the  $  character.  All  other  characters  are  treated  literally,  and  are  used  to  determine  the  nmap 
inpattern  variable  values.  For  example,  given  inpattern  $1.$2  and  the  remote  file  name 
my  data,  data,  $1  would  have  the  value  mydata,  and  $2  would  have  the  value  data.  Theout- 

pattern  determines  the  resulting  mapped  filename.  The  sequences  $1,  $2         $9  are  replaced  by 

any  value  resulting  from  the  inpattern  template.  The  sequence  $0  is  replaced  by  the  original 
filename.  Additionally,  the  sequence  [seql,  seq2]  is  replaced  by  seql  if  seql  is  not  a  null  string;  oth- 
erwise it  is  replaced  by  seq2.  For  example,  the  command  nmap  $1.$2.$3 
[$1,  $2]  .  [$2,  file]  would  yield  the  output  filename  myfile.data  for  input  filenames 
myfile.data  and  myfile  .  data .  old,  myf ile  .  f ile  for  the  input  filename  myfile,  and 
myf ile  .myf ile  for  the  input  filename  .myfile.  Spaces  can  be  included  in  outpattern,  as  in  the 
example:  nmap  $1  |  sed  "s/  *$//"  >  $1  .  Use  the  \  character  to  prevent  special 
treatment  of  the  $,  [,  ] ,  and  ,  characters. 

ntrans  [inchars  [outchars]] 

Set  or  unset  the  filename  character  translation  mechanism.  If  no  arguments  are  specified,  the 
filename  character  translation  mechanism  is  unset.  If  arguments  are  specified,  characters  in  remote 
filenames  are  translated  during  mput  commands  and  put  commands  issued  without  a  specified 
remote  target  filename.  If  arguments  are  specified,  characters  in  local  filenames  are  translated  dur- 
ing mget  commands  and  get  commands  issued  without  a  specified  local  target  filename.  This  com- 
mand is  useful  when  connecting  to  a  non-UNIX  remote  computer  with  different  file  naming  conven- 
tions or  practices.  Characters  in  a  filename  matching  a  character  in  inchars  are  replaced  with  the 
corresponding  character  in  outchars.  If  the  character's  position  in  inchars  is  longer  than  the  length  of 
outchars,  the  character  is  deleted  from  the  file  name. 

open  server-host  [port-number] 

Establish  a  connection  to  server-host,  using  port-number  (if  specified).  If  auto-login  is  enabled,  ftp 
attempts  to  log  into  the  server  host. 

prompt 

Toggle  interactive  prompting.  By  default,  ftp  prompts  the  user  for  a  yes  or  no  response  for  each 
output  file  during  multiple-file  commands.  If  interactive  prompting  is  disabled,  ftp  performs  the 
command  for  all  specified  files. 

put  I  oca  I -file  [remote-file] 

Copy  local -file  to  remote- file.  If  remote- file  is  unspecified,  ftp  assigns  the  local -file  name,  processed 
according  to  any  ntrans  or  nmap  settings,  to  the  remote-filename. 

pwd  Write  the  name  of  the  remote  working  directory  to  stdout. 

quit 

A  synonym  for  bye. 

quote  arguments 

Send  arguments,  verbatim,  to  the  server  host.  Seeftpd(lM). 

recv  remote-file  [local -file] 
A  synonym  for  get. 

reget  remote-file  [local -file] 

reget  acts  like  get,  except  that  if  local-file  exists  and  is  smaller  than  remote-file,  local-file  is 
presumed  to  be  a  partially  transferred  copy  of  remote-file  and  the  transfer  is  continued  from  the 
apparent  point  of  failure.  This  command  is  useful  when  transferring  very  large  files  over  networks 
that  tend  to  drop  connections. 

rhelp  [command-name] 

Request  help  from  the  server  host.  If  command-name  is  specified,  supply  it  to  the  server.  See 
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ftpd(lM). 
rstatus  [file-name] 

With  no  arguments,  show  status  of  remote  machine.  If  file-name  is  specified,  show  status  of  file-name 
on  remote  machine. 

rename  remote-from  remote-to 

Rename  remote-from,  which  can  be  either  a  file  or  a  directory,  to  remote-to. 

reset 

Clear  reply  queue.  This  command  re-synchronizes  command/reply  sequencing  with  the  remote  FTP 
server.  Resynchronization  may  be  necessary  following  a  violation  of  the  FTP  protocol  by  the  remote 
server. 

restart  marker 

Restart  the  immediately  following  get  or  put  at  the  indicated  marker.  On  UNIX  systems,  marker 
isusuallya  byte  offset  into  the  file. 

rmdir  remote-directory 

Delete  remote-directory,  remote-directory  must  bean  empty  directory. 

run i que 

Toggle  storing  of  files  on  the  local  system  with  unique  filenames.  If  a  file  already  exists  with  a  name 
equal  to  the  target  local  filename  for  a  get  or  mget  command,  a  .1  is  appended  to  the  name.  If 
the  resulting  name  matches  another  existing  file,  a  .2  is  appended  to  the  original  name.  I f  this  pro- 
cess continues  up  to  .  99,  an  error  message  is  printed,  and  the  transfer  does  not  take  place,  ftp 
reports  the  unique  filename.  Note  that  runique  does  not  affect  local  files  generated  from  a  shell 
command  (seebelow).  The  default  value  is  off. 

send  local -file  [remote-file] 
A  synonym  for  put . 

sendport 

Toggle  the  use  of  PORT  commands.  By  default,  ftp  attempts  to  use  a  PORT  command  when  estab- 
lishing a  connection  for  each  data  transfer.  If  the  PORT  command  fails,  ftp  uses  the  default  data 
port.  When  the  use  of  PORT  commands  is  disabled,  ftp  makes  no  attempt  to  use  PORT  commands 
for  each  data  transfer.  This  is  useful  for  certain  FTP  implementations  that  ignore  PORT  commands 
but  (incorrectly)  indicate  that  they've  been  accepted.  See  ftpd(lM).  Turning  sendport  off  may 
cause  delays  in  the  execution  of  commands. 

site  arguments 

Send  arguments,  verbatim,  to  the  server  host  as  a  SITE  command.  Seeftpd(llM). 

size  remote-file 

Show  the  size  of  remote- file. 

status 

Show  the  current  status  of  ftp. 

struct  [struct-name] 

Set  the  FTP  file  transfer  struct  to  struct-name.  The  only  supported  struct  is  file. 

s unique 

Toggle  storing  of  files  on  remote  machine  under  unique  file  names.  The  remote  server  reports  the 
uniquename.  By  default,  sunique  isoff. 

system 

Show  the  type  of  operating  system  running  on  the  remote  machine, 
tenex 

Set  the  FTP  file  transfer  type  to  tenex. 
type  [type-name] 

Set  the  FTP  file  transfer  type  to  type-name.  If  type-name  is  unspecified,  write  the  current  type  to 
stdout.  Ascii,  binary,  and  tenex  are  the  types  currently  supported. 

umask  [newmask] 

Set  the  default  umask  on  the  remote  server  to  newmask.  If  newmask  is  omitted,  the  current  umask  is 
printed. 
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user  user-name  [password ]  [account] 

Log  into  the  server  host  on  the  current  connection,  which  must  already  be  open.  A  .netrc  file  in 
the  user's  local  home  directory  can  provide  the  user-name,  password,  and  optionally  the  account;  see 
netrc(4).  Otherwise  ftp  prompts  the  user  for  this  information.  In  a  secure  environment  based  on 
Kerberos  V5,  ftp  will  not  require  a  password.  Instead,  Kerberos  authentication  and  authorization 
will  be  performed  as  described  in  sis(5).  In  all  other  environments,  users  are  considered  authenti- 
cated if  they  have  a  password  and  that  password  is  correct,  and  authorized  if  an  account  exists  for 
them  on  the  remote  system. 

verbose 

Toggle  verbose  output.  If  verbose  output  is  enabled,  ftp  displays  responses  from  the  server  host, 
and  when  a  filetransfer  completes  it  reports  statistics  regarding  the  efficiency  of  the  transfer. 

?  [  command  ] 

A  synonym  for  the  help  command.  Prints  the  help  information  for  the  specified  command. 

Aborting  A  File  Transfer 

To  abort  a  file  transfer,  use  the  terminal  interrupt  key  (usually  Ctrl-C).  Sending  transfers  are  halted 
immediately,  ftp  halts  incoming  (receive)  transfers  by  first  sending  a  FTP  protocol  ABOR  command  to 
the  remote  server,  then  discarding  any  further  received  data.  The  speed  at  which  this  is  accomplished 
depends  upon  the  remote  server's  support  for  ABOR  processing.  If  the  remote  server  does  not  support  the 
ABOR  command,  an  ftp>  prompt  does  not  appear  until  the  remote  server  completes  sending  the 
requested  file. 

The  terminal  interrupt  key  sequence  is  ignored  while  ftp  awaits  a  reply  from  the  remote  server.  A  long 
delay  in  this  mode  may  result  from  the  ABOR  processing  described  above,  or  from  unexpected  behavior  by 
the  remote  server,  including  violations  of  the  FTP  protocol.  If  the  delay  results  from  unexpected  remote 
server  behavior,  the  local  ftp  program  must  be  killed  manually. 

File  Naming  Conventions 

Files  specified  as  arguments  to  ftp  commands  are  processed  according  to  the  foil  owing  rules. 

•  If  the  file  name  -  is  specified,  ftp  uses  the  standard  input  (for  reading)  or  standard  output  (for  writ- 
ing). 

•  If  the  first  character  of  the  file  name  is  | ,  ftp  interprets  the  remainder  of  the  argument  as  a  shell 
command,  ftp  forks  a  shell,  using  popen()  (see  popen(3S))  with  the  supplied  argument,  and  reads 
(writes)  from  standard  output  (standard  input).  If  the  shell  command  includes  spaces,  the  argument 
must  be  quoted,  as  in: 

"I   Is  -It" 

Some  useful  examples  of  this  mechanism  are: 

Is   .    "|  more" 
The  above  command  lists  the  files  in  the  current  directory  page  by  page. 

put  " |   tail  -20  loc_file"  rem_file 
This  command  copies  the  last  twenty  lines  of  the  local  file  "loc  file"  to  the  remote  system  as  "rem  file". 

•  Otherwise,  if  globbing  is  enabled,  ftp  expands  local  file  names  according  to  the  rules  used  by  the  C 
shell  (see  csh(l));  see  the  glob  command,  below.  If  the  ftp  command  expects  a  single  local  file  (e.g. 
put),  only  the  first  filename  generated  by  the  globbing  operation  is  used. 

•  For  mget  commands  and  get  commands  with  unspecified  local  file  names,  the  local  filename  is  named 
the  same  as  the  remote  filename,  which  may  be  altered  by  a  case,  ntrans,  or  nmap  setting.  The 
resulting  filename  may  then  be  altered  if  runique  ison. 

•  For  mput  commands  and  put  commands  with  unspecified  remote  file  names,  the  remote  filename  is 
named  the  same  as  the  local  filename,  which  may  be  altered  by  a  ntrans  or  nmap  setting.  The 
resulting  filename  may  then  be  altered  by  the  remote  server  if  sunique  ison. 

WARNINGS 

Correct  execution  of  many  commands  depends  upon  proper  behavior  by  the  remote  server. 
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DIAGNOSTICS 

Error!    could  not  retrieve  authentication  type. 

Please  notify  sys  admin. 

There  are  two  authentication  mechanisms  used  by  ftp.  One  authentication  mechanism  is  based  on 
Kerberos  and  the  other  is  not.  The  type  of  authentication  mechanism  is  obtained  from  a  system  file 
which  is  updated  by  inetsvcssec(lM).  If  the  system  file  does  not  contain  known  authentication  types, 
the  above  error  is  displayed. 

AUTHOR 

ftp  was  developed  by  the  University  of  California,  Berkeley. 
SEE  ALSO 

csh(l),  rcp(l),  ftpd(lM),  inetsvcs  sec(lM),  netrc(4),  ftpusers(4),  hosts(4),  sis(5). 


Section  1-308 


-7- 


HP-UX  Release  Hi:  December  2000 


ftpcount(l) 


ftpcount(l) 


NAME 

ftpcount  -  show  current  number  of  users  for  each  class 

SYNOPSIS 

/ usr/bin/ ftpcount 

DESCRIPTION 

The  ftpcount  command  shows  the  current  number  of  users  (and  the  limit)  for  each  class  defined  in  the 
ftpaccess  file.  If  the  ftpaccess  file  does  not  exist,  the  ftpcount  command  will  not  display  anything. 
However,  if  the  ftpaccess  fileexists  and  it  i s  of  zero  bytes,  ftpcount  will  display  an  error  message: 

ftpcount: no  service  classes  defined,   no  usage  count  kept. 

EXIT  STATUS 

ftpcount  returns: 

0  successful 

1  failure 

AUTHOR 

ftpcount  was  developed  by  the  Washington  University,  St.  Louis,  Missouri. 

SEE  ALSO 

ftpwho(l),  ftpaccess(4). 
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NAME 

ftprestart  -  remove  the  shutdown  message  file  created  by  ftpshut  utility. 

SYNOPSIS 

/ usr/bin/ ftprestart 

DESCRIPTION 

The  ftprestart  command  removes  all  the  shutdown  message  files  from  the  real,  anonymous,  and  vir- 
tual user  accounts.  The  message  files  are  created  by  the  ftpshut  utility  in  the  path  as  specified  by  the 
'shutdown'  directive  in  the  /etc/ftpd/ftpaccess  file  (see  ftpshut(l)  for  more  details).  This  command 
is  always  used  after  the  ftpshut  command  is  executed. 

Note:  For  guest  user  accounts,  the  message  files  have  to  be  removed  manually.  The  removal  will  not  be 
done  by  the  ftprestart  command. 

EXIT  STATUS 

ftprestart  returns: 

0  successful 

1  failure 

AUTHOR 

ftprestart  was  developed  by  the  Washington  University,  St.  Louis,  Missouri. 

SEE  ALSO 

ftpshut(l),  ftpaccess(4). 
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NAME 

ftpshut  -  create  shutdown  message  file  to  shut  down  the  ftp  servers  at  a  given  time 
SYNOPSIS 

/usr/bin/ftpshut  [  -1  min  ]    [  -d  min  ]  time  [  warning-message  ...  ] 
DESCRIPTION 

The  ftpshut  command  provides  an  automated  shutdown  procedure  that  a  superuser  can  use  to  notify  ftp 
users  when  the  ftp  server  is  shutting  down.  This  command  will  create  a  shutdown  message  file  in  the  path 
specified  by  the  'shutdown'  directive  in  the  /etc/ftpd/ftpaccess  file  in  the  real,  anonymous  and  vir- 
tual user  accounts.  For  guest  accounts  the  system  administrator  must  copy  the  message  file  created  in  the 
real  user  account  to  the  guest  accounts  manually.  The  server  will  check  this  file  regularly  to  see  if  the 
server  is  going  to  be  shut  down. 

-1  min  This  option  is  used  as  deny  offset.  New  FTP  access  is  disabled  'min'  minutes  before 

shutdown.  The  default  value  of  'min'  is  10  minutes.  This  value  can  be  reset  by  the 
user. 

-d  min  This  option  is  used  as  disc  offset.  All  current  FTP  connections  will  be  dropped  'min' 

minutes  before  shutdown.  The  default  value  of  'min'  is  5  minutes.  This  value  can  be 
reset  by  the  user. 

time  time,  is  the  time  at  which  the  ftp  server  will  be  shutdown.  If  time  is  set  to  the  word 

'now"  the  shutdown  will  be  immediate,  time  can  also  be  set  to  a  future  time.  Future 
time  can  be  specified  in  one  of  the  two  formats:  +number  or  HHMM.  Thefirst  format 
brings  the  ftp  servers  down  in  number  minutes.  The  second  format  brings  the  ftp 
servers  down  at  the  time  of  day  indicated,  using  a  24-hour  clock  format. 

warning-message 

The  warning-message  is  the  message  the  server  will  flash  to  its  clients  on  shut  down. 
The  user  can  usea  message  of  his  choice  or  use  the 'macros' or  'magic  cookies' that  are 
available.  The  server  will  replace  the  macro  with  the  specified  text  string.  The 
warning-message  will  be  formatted  to  be  75  characters  long,  including  the  length  of 
any  expanded  macros  ("magic  cookies").  The  default  warning  message  is  "System  shut- 
down at  %s".  Thefollowing  magic  cookies  are  available: 


%s 

time  system  is  going  to  shut  down 

%r 

time  new  connections  will  be  denied 

%d 

time  current  connections  will  be  dropped 

%C 

current  working  directory 

%E 

the  maintainer's  email  address  as  defined  in  ftpaccess 

%L 

local  host  name 

%M 

maximum  allowed  number  of  users  in  this  class 

%N 

current  number  of  users  in  this  class 

%R 

remote  host  name 

%T 

local  time  (form  Thu  Nov  15  17:12:42  1990) 

%U 

username given  at  login  time 

WARNINGS 

You  can  kill  the  servers  only  between  now  and  23:59,  if  you  use  the  absolute  time  for  ftpshut. 

EXIT  STATUS 

ftpshut  returns: 

0  successful 

1  failure 

-1  the  wrong  parameter  was  passed  to  ftpshut . 
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AUTHOR 

ftpshut  was  devel  oped  by  the  Washington  University,  St.  Louis,  Missouri. 

SEE  ALSO 

ftpaccess(4). 
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NAME 

ftpwho-  show  current  process  information  for  each  ftp  user. 

SYNOPSIS 

/ usr/bin/ ftpwho 

DESCRIPTION 

The  ftpwho  command  shows  the  current  process  information  for  each  user  logged  into  the  ftp  server.  If 
the  f tpaccess  file  does  not  exist,  this  command  will  not  display  anything.  However,  if  the  ftpaccess  file 
exists  and  it  is  of  zero  bytes  then  this  command  will  display  an  error  message: 

ftpwho:   no  service  classes  defined,   no  usage  count  kept. 

EXIT  STATUS 

ftpwho  returns: 

0  successful 

1  failure 

AUTHOR 

ftpwho  was  developed  by  the  Washington  University,  St.  Louis,  Missouri. 

SEE  ALSO 

ftpcount(l),  ftpaccess(4). 
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NAME 

gencat  -  generate  a  formatted  message  catalog  file 

SYNOPSIS 

gencat  [-1]  catfile  msgfile  ... 

DESCRIPTION 

Message  catalogs  allow  a  program  to  process  input  and  produce  output  according  to  local  customs  and 
languages.  For  details,  see  Native  LanguageSupport  Users  Guide. 

The  gencat  command  merges  each  message  source  msgfile  into  a  formatted  message  catalog  catfile  that 
can  be  accessed  by  catgets  ()  (see  catgets(3C)).  If  catfiledoes  not  exist,  it  iscreated.  If  catfile  exists,  its 
messages  are  included  in  the  new  catfile.  If  set  and  message  numbers  collide,  the  new  message  text  in  file 
replaces  the  old  message  text  in  catfile.  A  msgfile  consists  of  message,  directive,  and  comment  lines  (all 
without  leading  spaces  or  tabs)  described  below.  Except  as  noted,  fields  are  separated  by  one  or  more  space 
or  tab  characters. 

If  -  is  specified  as  catalog  file,  standard  output  is  used. 

If  -  is  specified  for  an  instance  of  message  file,  standard  input  is  used. 

$set  s  [comment]  A  $set  directive  specifies  the  set  s,  of  the  messages  that  follow  until  the 
next  $set  or  end-of-file  appears.  The  set  number  s  is  an  unsigned  integer  in 
the  range  1  through  NL_SETMAX.  Any  string  following  the  set  number  is 
treated  as  a  comment.  If  a  $set  directive  is  not  specified,  messages  are  put 
i  n  the  default  set  NL_SETD . 

Set  numbers  must  bein  ascending  order  within  a  msgfilebut  need  not  be  con- 
tiguous. 

$delset  s  [comment]  A  $delset  directive  deletes  the  message  set  identified  by  the  set  number  s, 
from  an  existing  message  catalog.  Any  string  following  the  set  number  is 
treated  as  a  comment. 

m  messagetext  A  message  line  specifies  a  message  number  m,  and  associated  message  text. 

The  message  number  m  is  an  unsigned  integer  in  the  range  1  through 
NL_MSGMAX.  The  messagetext  is  a  C  string,  including  spaces,  tabs  and  \ 
(backslash)  escapes,  but  by  default  without  surrounding  quotes  (see  $quote 
directive  below).  The  message  number  m  is  separated  from  the  message  text 
by  a  single  space  or  tab  character.  The  message  text  begins  with  the  first 
character  following  the  separator  and  ends  at  new-line.  Extra  spaces  or  tabs 
(including  any  trailing  spaces  or  tabs)  are  considered  part  of  the 
messagetext. 

The  message  text  of  a  message  line  is  stored  in  catfile  with  message  number 
m  and  set  number  s  specified  by  the  most  recent  $set  directive. 

Message  numbers  must  be  in  ascending  order  within  a  set,  but  need  not  be 
contiguous. 

Note  that  the  space  or  tab  separator  distinguishes  insertion  of  a  null  message 
from  deletion  of  a  message.  If  a  message  line  has  a  number  and  separator 
but  no  text,  the  message  number  and  an  associated  null  message  string  are 
stored  in  catfile.  If  a  message  line  has  a  number  but  neither  separator  nor 
text,  the  message  number  and  its  associated  message  text  are  deleted  from 
catfile. 

-1  If  the  -1  option  is  specified,  the  length  of  message  text  must  be  no  more 

than  MAX_BUFLEN  -  1  bytes.  If  the  -1  option  is  not  specified,  the  length  of 
message  text  must  be  no  more  than  NL_TEXTMAX  bytes.  See  catgets(3C), 
for  message  length  limits  imposed  by  these  routines. 

$guote  [q  comment]  A  $guote  directive  specifies  a  quote  character  q,  used  to  surround 
message  text  and  make  leading  and  trailing  space  visible  in  a  message  line. 
Any  string  following  the  specified  quote  character  q  is  treated  as  a  comment. 
By  default,  or  if  a  quote  character  q  not  is  supplied,  quoting  of  message  text  is 
not  recognized. 
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$  comment  A  $  followed  by  a  space  or  tab  is  treated  as  a  comment  and  can  appear  any- 

where in  a  file.  A  line  consisting  of  zero  or  more  spaces  or  tabs  is  treated  as  a 
comment  line. 

NL_TEXTMAX,  NL_SETMAX ,  and  NL_MSGMAX  are  defined  in  <limits.h>.  NL_SETD  is  defined  in 
<nl_types  .  h>  .  MAX_BUFLEN  is  defined  in  <msgcat .  h>  . 

EXTERNAL  INFLUENCES 
Envi  ronment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  gencat  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL,  if  set  to  a  non-empty  string  value,  overrides  the  values  of  all  of  the  other  internationalization 
variables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogs  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

WARNINGS 

The  $guote  directive  is  not  currently  supported  on  the  HP  MPE  and  RTE  operating  systems. 
AUTHOR 

gencat  was  developed  by  HP  and  theX/Open  Company,  Ltd. 
SEE  ALSO 

dumpmsg(l),  findmsg(l),  insertmsg(l),  catgets(3C),  catopen(3C). 
Native  LanguageSupport  Users  Guide. 

STANDARDS  CONFORMANCE 

gencat:  XPG2,  XPG3 
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NAME 

genxlt  -  generate  iconv  translation  tables 
SYNOPSIS 

genxlt  [-f  outputfilename]  [inputfilename] 
DESCRIPTION 

genxlt  generates  a  compiled,  non-readable  binary  version  of  the  iconv  table  that  is  suitable  for  use  by 
iconv(l)  and  iconv(3C).  If  input  filename  or  output  filename  is  not  supplied,  standard  input  and/or  stan- 
dard output  will  be  used. 

Since  the  output  of  genxlt  is  a  binary,  non-readable  file,  if  the  -f  option  is  not  used,  the  redirection 
symbol  >  maybe  used  to  redirect  the  standard  output  to  a  file. 

Options 

genxlt  recognizes  the  following  options: 
-f  output  filename 

If  this  option  is  not  selected,  the  data  will  be  sent  to  standard  output,  from  where  it 
could  be  redirected  to  a  file. 

genxlt  creates  tables  that  are  in  a  prescribed  format  and  which  can  be  interpreted  by  the  default  conver- 
sion routines  of  iconv(3C).  The  input  file  has  two  columns,  giving  the  filecode  mapping  between  the  two 
codesets.  The  entries  are  in  hexadecimal. 

The  input  file  must  be  formatted  as  two  columns  of  hexadecimal  digits.  Characters  in  the  first  column  are 
translated  into  the  characters  in  the  second  column.  Lines  preceded  with  #  in  the  first  column  are  ignored 
as  comments  on  all  lines  except  in  the  case  of  the  foil  owing  keywords:  #Galley:  and  WVhat: 

I  n  addition  to  the  data,  which  defines  the  filecode  mapping,  a  Galley  character  (see  iconv(3C))  may  also  be 
defined  for  that  particular  conversion.  This  is  done  by  adding  the  line  #Galley :  Oxnnnn,  to  the  begin- 
ning of  the  input  file.  The  nnnn  is  any  multi-byte  character  (see  EXAMPLES).  A  What  string  (see 
what(l)),  may  also  be  defined  in  the  input  file  using  the  entry  #What:  <any_string>.  This  string  may 
contain  information  like  version  number,  type  of  conversion,  etc.,  which  are  not  used  in  any  way  for  the 
conversions.  Note  that  if  the  What  string  is  defined,  it  should  appear  before  the  Galley  definition. 

EXTERNAL  INFLUENCES 
Envi  ronment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  genxlt  will  behave  as  if  all  internationalization  variables  are  set  to  "C"  (see 
envi  ron(5)). 

If  LC_ALL  is  set  to  a  non-empty  string  value,  it  overrides  the  values  of  all  the  other  internationalization 
variables. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Singleand  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

The  exit  values  are: 

0       Successful  completion. 
>0       Error  condition  occurred. 

EXAMPLES 

This  example  compiles  the  iconvinput  and  puts  the  output  binary  in 
/usr/lib/nls/iconv/tables/roma8=iso81 .  The  following  iconv  statement  uses  the 
roma8=iso81  tableto  convert  the  datafilefrom  code  set  roman8  to  code  set  iso8859-l . 

%  genxlt  iconv_input   >  /usr/lib/nls/iconv/tables/roma8=iso81 
%  iconv  -f  roma8  -t  iso81  data_file 
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This  is  an  example  of  the  input  file: 

#What :   CodesetA  to  CodesetB :   version  1 . 0 
#Galley:  Oxffff 

#  the  conversion  data  is  as  follows : 
0x01  0x01 
0x02  0x42 

0xff87  0x4567 

etc . 
WARNINGS 

Because  genxlt  will  write  over  the  existing  table,  it  is  wise  to  save  the  existing  table  into  another  file 
before  using  genxlt . 

Warnings  are  not  given  for  incorrect  data  in  the  input  file. 

You  must  have  super-user  privileges  to  install  files  in  /usr/lib/nls/iconv/tables. 
FILES 

/usr/lib/nls/iconv/tables       All  tables  must  be  installed  in  this  directory. 

SEE  ALSO 

dmpxlt(l),  iconv(l),  iconv(3C). 

STANDARDS  COMPLIANCE 

genxlt:  XPG4 tables 
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NAME 

get  -  get  a  version  of  an  SCCS  file 
SYNOPSIS 

get  [-r  SID]  [-c  cutoff]  [-e]  [-b]  [-i  list]  [-x  list]  [-k]  [-l[p]]  [-p]  [-s]  [-m]  [-n]  [-g]  [-t] 
[-w  string]  [-a  seq-number]  file  ... 

DESCRIPTION 

The  get  command  generates  an  ASCI  I  text  file  from  each  named  SCCS  file  according  to  the  specifications 
given  by  its  option  arguments,  which  begin  with  -.  The  arguments  can  be  specified  in  any  order,  but  all 
option  arguments  apply  to  all  named  SCCS  files.  If  a  directory  is  named,  get  behaves  as  if  each  file  in  the 
directory  was  specified  as  a  named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name  does 
not  begin  with  s.)  and  unreadable  files  are  silently  ignored.  If  a  file  name  of  -  is  given,  the  standard 
input  is  read  and  each  line  of  the  standard  input  is  assumed  to  be  the  name  of  an  SCCS  file  to  be  processed. 
Again,  non-SCCS  files  and  unreadablefiles  are  silently  ignored. 

The  generated  text  is  normally  written  into  a  file  called  the  g-file  whose  name  is  derived  from  the  SCCS  file 
name  by  simply  removing  the  s .  prefix  (see  Fl  LES  below). 

Options 

Explanation  of  the  option  arguments  below  is  based  on  processing  only  one  SCCS  file.  When  processing 
multipleSCCS  files,  the  effects  of  any  option  argument  applies  independently  to  each  named  file. 

-rSID  The  SCCS  I Dentification  string  (SID)  of  the  version  (delta)  of  an  SCCS  file  to  be 

retrieved.  Table  1  shows,  for  the  most  useful  cases,  which  version  of  an  SCCS  file  is 
retrieved  (as  well  as  the  SI  D  of  the  version  to  be  eventually  created  by  delta  if  the 
-e  option  is  also  used),  as  a  function  of  the  SI  D  specified  (see  delta(l)). 

-ccutoff         cutoff  date-ti  me,  i  n  the  form: 

YY[M  M  [DD[H  H  [M  M  [SS]  ]  ]  ]  ] 

No  changes  (deltas)  to  the  SCCS  file  which  were  created  after  the  specified  cutoff 
date-time  are  included  in  the  generated  ASCI  I  text  file.  Units  omitted  from  the  date- 
time  default  to  their  maximum  possible  values;  that  is,  -c7502  is  equivalent  to 
-c750228235959.  Any  number  of  non-numeric  characters  can  separate  the  vari- 
ous 2-digit  pieces  of  the  cutoff  date-time.  This  feature  allows  one  to  specify  a  cutoff 
date  in  the  form:  -c77/2/2  9:22:25.  Note  that  this  implies  that  one  can  use  the 
%E%  and  %U%  identification  keywords  (see  below)  for  nested  gets  within  a  command: 

~!get  "-c%E%  %U%"  s . f ile 

-e  I  ndicates  that  the  get  is  for  the  purpose  of  editing  or  making  a  change  (delta)  to  the 

SCCS  file  via  a  subsequent  use  of  delta.  The-e  option  used  in  a  get  for  a  particu- 
lar version  (SID)  of  the  SCCS  file  prevents  further  gets  for  editing  on  the  same  SID 
until  delta  is  executed  or  the  j  (joint  edit)  flag  is  set  in  the  SCCS  file  (see 
admin(l)).  Concurrent  use  of  get  -e  for  different  SI Ds  is  always  allowed.  Note, 
however,  that  only  one  user  is  permitted  to  do  a  concurrent  get  -e  (see  admin(l)). 

If  the  g-file  generated  by  get  with  an  -e  option  is  accidentally  ruined  in  the  process 
of  editing  it,  it  can  be  regenerated  by  re-executing  the  get  command  with  the  -k 
option  in  pi  ace  of  the-e  option. 

SCCS  file  protection  specified  via  the  ceiling,  floor,  and  authorized  user  list  stored  in 
the  SCCS  file  (see  admin  (1))  are  enforced  when  the-e  option  is  used. 

-b  Used  with  the  -e  option  to  indicate  that  the  new  delta  should  have  an  SID  in  a  new 

branch  as  shown  in  Table  1.  This  option  is  ignored  if  theb  flag  is  not  present  in  the 
file  (see  admin(l))  or  if  the  retrieved  delta  is  not  a  leaf  delta.  (A  leaf  delta  is  one  that 
has  no  successors  on  the  SCCS  file  tree.) 

Note:  A  branch  delta  can  always  be  created  from  a  non-leaf  delta. 

-ilist  A  list  of  deltas  to  be  included  (forced  to  be  applied)  in  the  creation  of  the  generated 

file.  The  list  has  the  foil  owing  syntax: 

list  ::=  range  |  list,  range 
range ::=  SID  |  SID  -  SID 
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SID,  the  SCCS  Identification  of  a  delta,  can  be  in  any  form  shown  in  the  "SID 
Specified"  column  of  Table  1.  Partial  SIDs  are  interpreted  as  shown  in  the  "SID 
Retrieved"  column  of  Table  1.  See  WARNINGS. 

-xlist  A  list  of  deltas  to  be  excluded  (forced  not  to  be  applied)  in  the  creation  of  the  gen- 

erated file.  Seethe-i  option  for  the  list  format. 

-k  Suppresses  replacement  of  identification  keywords  (see  below)  in  the  retrieved  text  by 

their  value.  The-k  option  is  implied  by  the  -e  option. 

-l[p]  Causes  a  delta  summary  to  be  written  into  an  l-file.  If  -lp  is  used,  an  l-file  is  not 

created;  the  delta  summary  is  written  on  the  standard  output  instead.  See  FILES  for 
the  format  of  the  l-file.  The  user  must  have  s-file  read  permission  in  order  to  use  the 
-1  option. 

-p  Causes  the  text  retrieved  from  the  SCCS  file  to  be  written  on  the  standard  output. 

No  g-file  is  created.  All  output  that  normally  goes  to  the  standard  output  goes  to  file 
descriptor  2  (standard  error)  instead,  unless  the  -s  option  is  used,  in  which  case  it 
disappears. 

-s  Suppresses  all  output  normally  written  on  the  standard  output.  However,  fatal  error 

messages  (which  always  go  to  file  descriptor  2)  remain  unaffected. 

-m  Causes  each  text  line  retrieved  from  the  SCCS  file  to  be  preceded  by  the  SID  of  the 

delta  that  inserted  the  text  line  in  the  SCCS  file.  The  format  is:  SID,  followed  by  a 
horizontal  tab,  followed  by  the  text  line. 

-n  Causes  each  generated  text  line  to  be  preceded  with  the  %M%  identification  keyword 

value  (see  below).  The  format  is:  %M%  value,  followed  by  a  horizontal  tab,  followed  by 
the  text  line.  When  both  the  -m  and  -n  options  are  used,  the  format  is:  %M%  value, 
followed  by  a  horizontal  tab,  followed  by  the  -m  option-generated  format. 

-g  Suppresses  the  actual  retrieval  of  text  from  the  SCCS  file.  It  is  primarily  used  to  gen- 

erate an  l-file,  or  to  verify  the  existence  of  a  particular  SI  D. 

-t  Used  to  access  the  most  recently  created  ("top")  delta  in  a  given  release  (e.g.,  -rl),  or 

release  and  level  (e.g.,  -rl.2). 

-w  string        Substitute  string  for  all  occurrences  of  @%M%  when  getting  the  file. 

-aseq-number  The  delta  sequence  number  of  the  SCCS  file  delta  (version)  to  be  retrieved  (see 
sccsfile(4)).  This  option  is  used  by  the  comb  command  (see  comb(l));  it  is  not  a  gen- 
erally useful  option,  and  should  be  avoided.  If  both  the  -r  and  -a  options  are 
specified,  the  -a  option  is  used.  Care  should  be  taken  when  using  the  -a  option  in 
conjunction  with  the  -e  option,  because  the  SI  D  of  the  delta  to  be  created  may  not  be 
what  one  expects.  The  -r  option  can  be  used  with  the  -a  and  -e  options  to  control 
the  naming  of  the  SI  D  of  the  delta  to  be  created. 

For  each  file  processed,  get  responds  (on  the  standard  output)  with  the  SID  being  accessed  and  with  the 
number  of  lines  retrieved  from  the  SCCS  file. 

If  the  -e  option  is  used,  the  SID  of  the  delta  to  be  made  appears  after  the  SID  accessed  and  before  the 
number  of  lines  generated.  If  there  is  more  than  one  named  file,  or  if  a  directory  or  standard  input  is 
named,  each  file  name  is  printed  (preceded  by  a  new-line)  before  it  is  processed.  If  the  -i  option  is  used 
included  deltas  are  listed  following  the  notation  "Included".  If  the  -x  option  is  used,  excluded  deltas  are 
listed  following  the  notation  "Excluded". 
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Table  1.  Determination  of  SCCS  Identification  String 

SID* 

-b  Option 

Other 

SID 

SI  D  of  Delta 

Specified 

Used  % 

Conditions 

Retrieved 

to  be  Created 

none  %% 

no 

R  defaults  to  mR 

mR.mL 

mR.(mL+l) 

none  %% 

yes 

R  defaults  to  mR 

mR.mL 

mR.mL.  (mB+l).l 

R 

no 

R  >  mR 

mR.mL 

■j  i 

K 

no 

R  =  mR 

mR.mL 

i-v\D   / i-v»l     i  1  \ 

mK.^iTiL  +1} 

R 

R  >  mR 

mR  ml_ 

mR  ml  1 

lllr\.llll_.\lilD  T±  / .  x 

R 

r  =  mR 

mR  mL 

mR  ml  1 

lllr\.llll_.\lilD  tj.  / .  J. 

R 

r\  ^>  I  I  lr\  dl  1  u 

hR  mL** 

hR  ml  fmR+'H  1 

llr\.llll_.\lilD  T±  / .  A. 

R  does  not  exist 

R 

_ 

Trunk  succ.# 

R.mL 

R.mL.(mB+l).l 

i  n  rel  ease  >  R 

and  R  exists 

R.L 

no 

No  trunk  succ. 

R.L 

R.(L+1) 

R.L 

yes 

No  trunk  succ. 

R.L 

R.L.(mB+l).l 

R  1 

\  1  Ul  lis.  bULL. 

R  1 

r\ .  l  .  \  \  i  id      .  J. 

i  n  rel  ease  >  R 

R.L.B 

no 

No  branch  succ. 

R.L.B.mS 

R.L.B.(mS+l) 

R.L.B 

yes 

No  branch  succ. 

R.L.B.mS 

R.L.(mB+l).l 

R.L.B.S 

no 

No  branch  succ. 

R.L.B.S 

R.L.B.(S+1) 

R.L.B.S 

yes 

No  branch  succ. 

R.L.B.S 

R.L.(mB+l).l 

R.L.B.S 

Branch  succ. 

R.L.B.S 

R.L.(mB+l).l 

Notes  for  Table  1 

*  "R",  "L",  "B",  and  "S"  are  the  "release",  "level",  "branch",  and  "sequence"  components  of  the 
SI  D,  respectively;  "m"  means  "maximum".  Thus,  for  example,  "R.mL"  means  "the  maximum 
level  number  within  release  R";  "R.L.(mB+l).l"  means  "the  first  sequence  number  on  the 
new  branch  (i.e.,  maximum  branch  number  pi  us  one)  of  level  L  within  releaseR".  Note  that 
if  the  SID  specified  is  of  the  form  "R.L",  "R.L.B",  or  "R.L.B.S",  each  of  the  specified  com- 
ponents must  exist. 

**  "hR"  is  the  highest  existing  release  that  is  lower  than  the  specified,  nonexistent,  releaseR. 

***         This  is  used  to  force  creation  of  the  first  delta  in  a  new  release. 

#  Successor. 

%  The-b  option  is  effective  only  if  theb  flag  (see  admin(l))  is  present  in  the  file.  An  entry  of 

-  means  "irrelevant". 

%%  This  case  applies  if  the  d  (default  SID)  flag  is  not  present  in  the  file.  If  the  d  flag  is  present 
in  the  file,  then  the  SI  D  obtained  from  the  d  flag  is  interpreted  as  if  it  had  been  specified  on 
the  command  line.  Thus,  one  of  the  other  cases  in  thistableapplies. 

I  dentification  Keywords 

Identifying  information  is  inserted  into  the  text  retrieved  from  the  SCCS  file  by  replacing  identification  key- 
words with  their  val ue  wherever  they  occur.  The  following  keywords  can  be  used  in  the  text  stored  in  an 
SCCS  file: 

Keyword  Value 

%M%  Module  name:  either  the  value  of  the  m  flag  in  the  file  (see  admin(l)),  or  if  absent,  the 

name  of  the  SCCS  file  with  the  leadings,  removed. 

%I%  SCCS  identification  (SI  D)  (%R%  .  %L%  .  %B%  .  %S%)  of  the  retrieved  text. 
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%R%  Release. 

%L%  Level. 

%B%  Branch. 

%S%  Sequence. 

%D%  Current  date  (YY/M  M/DD). 

%H%  Current  date  (MM/DD/YY). 

%T%  Currenttime(HH:MM:SS). 

%E%  Date  newest  applied  delta  was  created  (YY/M M/DD). 

%G%  Date  newest  applied  delta  was  created  (MM/DD/YY). 

%U%  Time  newest  applied  delta  was  created  (HH  :MM:SS). 

%Y%  Module  type:  value  of  the  t  flag  in  the  SCCS  file  (see  admin  (1)). 

%F%  SCCS  filename. 

%P%  Fully  qualified  SCCS  file  name. 

%Q%  The  value  of  the  q  flag  in  the  file  (see  admin  (1)). 

%C%  Current  line  number.  This  keyword  is  intended  for  identifying  messages  output  by  the  pro- 
gram such  as  "this  should  not  have  happened"  type  errors.  It  is  not  intended  to  be  used  on 
every  line  to  provide  sequence  numbers. 

%Z%  The4-character  string  @  (#)  recognizable  by  what  (see  what(l)). 

%W%  A  shorthand  notation  for  constructing  what(l)  strings  for  HP-UX  system  program  files. 

%  W%  =%  Z  %  %M%  hor  i  zonta  I  -ta  b  %  I  % 

%A%  Another  shorthand  notation  for  constructing  what(l)  strings  for  non-HP-UX  system  pro- 

gram files. 

%A%  =  %z%%Y%  %M%  %i%%z% 


EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single- and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set 
to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  vari- 
able contains  an  invalid  setting,  get  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

Usesccshelp(l)  for  explanations. 

WARNINGS 

If  the  effective  user  has  write  permission  (either  explicitly  or  implicitly)  in  the  directory  containing  the 
SCCS  files,  but  the  real  user  does  not,  then  only  one  file  can  be  named  when  the  -e  option  is  used. 

Unexpected  results  occur  when  using  the  -i  option  to  merge  changes  into  sections  of  a  file  that  have  been 
(perhaps  inadvertently)  deleted  and  subsequently  re-inserted  into  a  file. 

An  l-filecannot  be  generated  when  -g  is  used.  In  other  words,  -g  -1  does  not  work. 
FILES 

Several  auxiliary  files  can  be  created  by  get.  These  files  are  known  generically  as  the  g-file,  l-file,  p-file, 
and  z-file.  The  letter  before  the  hyphen  is  called  the  tag.  An  auxiliary  file  name  is  formed  from  the  SCCS 
file  name:  the  last  component  of  all  SCCS  file  names  must  be  of  the  form  s .  module-name,  the  auxiliary 


HP-UX  Release  Hi:  December  2000 


-4- 


Section  1-321 


get(l) 


get(l) 


files  are  named  by  replacing  the  leading  s  with  the  tag.  The  g-file  is  an  exception  to  this  scheme:  the  g-file 
is  named  by  removing  the  s  .  prefix.  For  example,  s  .xyz .  c,  the  auxiliary  file  names  would  be  xyz .  c, 
1  .xyz .  c,  p. xyz  .  c,  and  z  .xyz  .  c,  respectively. 

The  g-file,  which  contains  the  generated  text,  is  created  in  the  current  directory  (unless  the  -p  option  is 
used).  A  g-file  is  created  in  all  cases,  whether  or  not  any  lines  of  text  were  generated  by  the  get.  It  is 
owned  by  the  real  user.  If  the  -k  option  is  used  or  implied  its  mode  is  644;  otherwise  its  mode  is  444.  Only 
the  real  user  need  have  write  permission  in  the  current  directory. 

The  I -file  contains  a  table  showing  which  deltas  were  applied  in  generating  the  retrieved  text.  The  I -file  is 
created  in  the  current  directory  if  the  -1  option  is  used;  its  mode  is  444  and  it  is  owned  by  the  real  user. 
Only  the  real  user  need  have  write  permission  in  the  current  directory. 

Lines  in  the  I -file  have  the  foil  owing  format: 

1.  A  blank  character  if  the  delta  was  applied; 

*  otherwise. 

2.  A  blank  character  if  the  delta  was  applied  or  was  not  applied  and  ignored; 

*  if  the  delta  was  not  applied  and  was  not  ignored. 

3.  A  code  indicating  a  "special"  reason  why  the  delta  was  or  was  not  applied: 

I:  Included. 
X:  Excluded. 
C:     Cut  off  (by  a  -c  option). 

4.  Blank. 

5.  SCCS  identification  (SID). 

6.  Tab  character. 

7.  Creation  date  and  time  (in  the  form  YY/MM/DD  HH:MM:SS). 

8.  Blank. 

9.  Login  name  of  person  who  created  delta. 

The  comments  and  MR  data  follow  on  subsequent  lines,  indented  one  horizontal  tab  character.  A 
blank  line  terminates  each  entry. 

The  p-file  is  used  to  pass  information  resulting  from  a  get  with  an  -e  option  along  to  delta.  Its  contents 
are  also  used  to  prevent  a  subsequent  execution  of  get  with  an  -e  option  for  the  same  SI  D  until  delta  is 
executed  or  the  joint  edit  flag,  j,  (see  admin(l))  is  set  in  the  SCCS  file.  The  p-file  is  created  in  the  direc- 
tory containing  the  SCCS  file  and  the  effective  user  must  have  write  permission  in  that  directory.  Its  mode 
is  644  and  it  is  owned  by  the  effective  user.  The  format  of  the  p-file  is:  the  gotten  SI  D,  followed  by  a  blank, 
followed  by  the  SI  D  that  the  new  delta  will  have  when  it  is  made,  followed  by  a  blank,  followed  by  the  login 
name  of  the  real  user,  followed  by  a  blank,  followed  by  the  date-time  the  get  was  executed,  followed  by  a 
blank  and  the  -i  option  argument  if  it  was  present,  followed  by  a  blank  and  the  -x  option  argument  if  it 
was  present,  followed  by  a  new-line.  There  can  be  an  arbitrary  number  of  lines  in  the  p-file  at  any  time;  no 
two  lines  can  have  the  same  new  delta  SI  D. 

The  z-file  serves  as  a  lock-out  mechanism  against  simultaneous  updates.  Its  contents  are  the  binary  (2 
bytes)  process  I D  of  the  command  (i.e.,  get)  that  created  it.  The  z-file  is  created  in  the  directory  contain- 
ing the  SCCS  file  for  the  duration  of  get.  The  same  protection  restrictions  as  those  for  the  p-file  apply  for 
thez-file.  The  z-file  is  created  mode  444. 

SEE  ALSO 

admin(l),  delta(l),  prs(l),  sccshelp(l),  what(l),  sccsfile(4). 

STANDARDS  CONFORMANCE 

get:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4 
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NAME 

getaccess  -  list  access  rights  to  filers) 
SYNOPSIS 

getaccess  [-u  user]  [-g  user]  group  [.group  ]...  ]  [-n]  file  ... 
getaccess  -r  [-n]  file  ... 

DESCRIPTION 

getaccess  lists  for  the  specified  files  the  effective  access  rights  of  the  caller  (that  is,  for  their  effective 
user  id,  effective  group  id,  and  supplementary  groups  list).  By  default,  the  command  prints  a  symbolic 
representation  of  the  user's  access  rights  to  the  named  file:  r  or  -  for  read/no  read,  w  or  -  for  write/no 
write,  and  x  or  -  for  execute/no  execute  (for  directories,  search/no  search),  followed  by  the  file  name. 

Options 

getaccess  recognizes  the  following  options  and  command-line  arguments: 

-u  user  List  access  for  the  given  user  instead  of  the  caller.  A  user  can  be  a  known  user  name, 

a  valid  id  number,  or  @  representing  the  file's  owner  id.  If  information  about  more 
than  one  file  is  requested,  the  value  of  @can  differ  for  each. 

This  option  sets  the  user  id  only.  The  access  check  is  made  with  the  caller's  effective 
group  id  and  supplementary  group  ids  unless  -g  is  also  specified. 

-g  group!, group]...] 

List  access  for  the  given  group(s)  instead  of  the  caller's  effective  group  id  and  supple- 
mentary groups  list.  A  group  can  be  a  known  group  name,  a  valid  id  number,  or  @ 
representing  the  file's  group  id.  If  information  about  more  than  one  file  is  requested, 
the  value  of  @can  differ  for  each. 

-r  List  access  using  the  caller's  real  user  id,  group  id,  and  supplementary  groups  list, 

instead  of  effective  id  values. 

-n  List  access  rights  numerically  (octal  digits  0..7  instead  of  rwx)  for  each  file  requested. 

The  bit  values  R_OK,  W_OK,  and  X_OK  are  defined  in  the  file  <unistd.h>. 

Checking  access  using  access  control  lists  is  described  in  acl  (5)  and  aclv(5). 

In  addition,  the  write  bit  is  cleared  for  files  on  read-only  file  systems  or  shared-text  programs  being  exe- 
cuted. The  execute  bit  is  not  turned  off  for  shared-text  programs  open  for  writing  because  it  is  not  possible 
to  ascertain  whether  a  file  open  for  writing  is  a  shared-text  program. 

Processes  with  appropriate  privileges  have  read  and  write  access  to  all  files.  However,  write  access  is 
denied  for  files  on  read-only  file  systems  or  shared-text  programs  being  executed.  Execute  access  is  allowed 
if  and  only  if  the  file  is  not  a  regular  file  or  the  execute  bit  is  set  in  any  of  the  file's  ACL  entries. 

To  use  getaccess  successfully,  the  caller  must  have  search  access  in  every  directory  component  of  the 
path  name  of  the  file,  getaccess  verifies  search  access  first  by  using  the  caller's  effective  IDs,  regard- 
less of  the  user  and  group  IDs  specified.  This  is  distinct  from  the  case  in  which  the  caller  can  search  the 
path  but  the  user  for  whom  access  is  being  checked  does  not  have  access  to  the  file. 

Note:  a  file  name  argument  of  -  has  no  special  meaning  (such  as  standard  input)  to  getaccess . 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 
If  any  internationalization  variable  contains  an  invalid  setting,  getaccess  behaves  as  if  all  internation- 
alization variables  are  set  to  "C".  See  environ  (5). 

RETURN  VALUE 

getaccess  returns  one  of  the  following  values: 

0  Successful  completion. 

1  getaccess  was  invoked  incorrectly  or  encountered  an  unknown  user  or  group  name.  An 
appropriate  message  is  printed  to  standard  error. 
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2     A  file  is  nonexistent  or  unreachable  (by  the  caller),    getaccess  prints  an  appropriate  mes- 
sage to  standard  error,  continues,  then  returns  a  value  of  2  upon  completion. 

EXAMPLES 

The  following  command  prints  the  caller's  access  rights  to  filel  using  the  file's  group  id  instead  of  the 
caller's  effective  group  id  and  groups  list. 

getaccess  -g@  filel 

Here's  how  to  check  access  by  user  ggd  in  groups  red  and  19  to  all  files  in  the  current  directory,  with 
access  rights  expressed  as  octal  values. 

getaccess  -u  ggd  -g  red, 19  -n   . *  * 

Here's  how  to  list  access  rights  for  all  files  under  mydir. 

find  mydir  -print    |   sort    |   xargs  getaccess 

AUTHOR 

getaccess  was  developed  by  HP. 

FILES 

/etc/passwd 
/etc /group 

SEE  ALSO 

chacl(l),  getacl(l),  Isacl(l),  setacl(l),  getaccess(2),  glossary(9). 
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NAME 

getacl  -  list  access  control  lists  (ACLs)  for  files  (J  FS  FileSystems  only) 

SYNOPSIS 

/usr/bin/getacl  [-ad]  file... 

DESCRIPTION 

For  each  argument  that  is  a  regular  file,  special  file,  or  named  pipe,  getacl  displays  the  owner,  group, 
and  the  Access  Control  List  (ACL).  For  each  directory  argument,  getacl  displays  the  owner,  group,  and 
theACL  and/or  the  default  ACL.  Only  directories  contain  default  ACLs. 

With  the  -a  option  specified,  the  filename,  owner,  group,  and  the  ACL  of  the  file  will  be  displayed.  With 
the  -d  option  specified,  the  filename,  owner,  group,  and  the  default  ACL  of  the  file,  if  it  exists,  will  be 
displayed.  With  options  not  specified,  the  filename,  owner,  group,  and  both  theACL,  and  the  default  ACL, 
if  it  exists,  will  be  displayed. 

This  command  may  be  executed  on  a  file  system  that  does  not  support  ACLs.  It  will  report  the  ACL  con- 
sisting of  only  the  owning  user,  owning  group,  class  and  other  entries,  based  on  the  permission  bits. 

When  multiple  files  are  specified  on  the  command  line,  a  blank  line  will  separate  the  ACL  for  each  file.  The 
format  of  an  ACL  is: 

#  file:  filename 

#  owner:  uid 

#  group:  gid 
user :  :  perm 
user :  uid  :  perm 
group :  :  perm 
group:  gid  :  perm 
class :  perm 
other :  perm 
default :  user :  :  perm 
default :  user :  uid:  perm 
default :  group :  :  perm 
default :  group :  gid  :  perm 
default :  class  :  perm 
default :  other :  perm 

The  first  three  lines  show  the  filename,  the  file  owner,  and  the  file  owning  group.  Note  that  when  only  the 
-d  option  is  specified,  and  the  file  has  no  default  ACL,  only  these  three  lines  will  be  displayed. 

The  user  entry  without  a  user  I D  indicates  the  permissions  that  will  be  granted  to  the  owner  of  the  file. 
One  or  more  additional  user  entries  indicate  the  permissions  that  will  be  granted  to  the  specified  users. 
The  group  entry  without  a  group  identifier  indicates  the  permissions  that  will  be  granted  to  the  owning 
group  of  the  file.  One  or  more  additional  group  entries  indicate  the  permissions  that  will  be  granted  to 
the  specified  groups.  Theother  entry  indicates  the  permissions  that  will  be  granted  to  others. 

The  default  entries  (default :  user ,  default :  group,  and  default :  other)  may  only  exist  for 
directories,  and  indicate  the  default  user,  group,  and  other  entries  that  will  be  added  toa  filecreated  within 
the  directory. 

The  uid  is  a  login  name,  or  a  user  I D  if  there  is  no  entry  for  the  uid  in  the  system's  password  file;  gid  is  a 
group  name,  or  a  group  ID  if  there  is  no  entry  for  the  gid  in  the  system's  group  file;  and  perm  is  a  three 
character  string  composed  of  the  letters  representing  the  separate  discretionary  access  rights:  r  (read),  w 
(write),  x  (execute/search),  or  the  placeholder  character  -  .The  perm  will  be  displayed  in  the  following 
order:  rwx .  Ifapermissionisnot  ACL  entry,  the  placeholder  character  will  appear. 

TheACL  entries  will  be  displayed  in  the  order  in  which  they  will  be  evaluated  when  an  access  check  is  per- 
formed. The  default  ACL  entries  which  may  exist  on  a  directory  have  no  effect  on  access  checks. 

The  file  owner  permission  bits  represent  the  access  that  the  owning  user  ACL  entry  has.  The  file  group 
class  permission  bits  represent  the  most  access  that  any  additional  user  entry,  additional  group  entry,  or 
the  owning  group  entry  may  grant.  The  file  other  permission  bits  represent  the  access  that  the  other  ACL 
entry  has.  If  a  user  invokes  the  chmod  command  and  changes  the  file  group  class  permission  bits,  the 
access  granted  by  the  additional  ACL  entries  may  be  restricted. 

In  order  to  indicate  that  the  file  group  class  permission  bits  restrict  an  ACL  entry,  getacl  will  display, 
after  each  affected  entry,  text  in  the  form  #ef fective :  perm,  where  perm  will  show  only  the 
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permissions  actual ly  granted. 
EXAMPLES 

Given  file  f  ilea,  with  an  ACL  six  entries  long,  the  command 

$  getacl  filea 
would  print: 

#  file:  filea 

#  owner:  fletcher 

#  group :  us 
user : : rwx 

user: spy:  

user : archer : rw- 
group : : r — 
class : rw- 
other :  

Given  file  filea,  with  an  ACL  six  entries  long,  after  the  command  chmod  700  filea  was  issued,  the 
command 

$  getacl  filea 

would  print: 

#  file:  filea 

#  owner:  fletcher 

#  group :  us 
user : : rwx 
user: spy:  

user : archer : rw-  #effective:  

group: :r —  #effective:  

class :  

other :  

Given  directory  fileb,  with  an  ACL  containing  default  entries,  the  command 

$  getacl  -d  fileb 
would  print: 

#  file:  fileb 

#  owner:  fletcher 

#  group :  us 
default : user : : rwx 

default : user : spy :  

default : group : : r — 
default : other :  

Given  directory  fileb,  the  command 

$  getacl  fileb 

would  print: 

#  file:  fileb 

#  owner:  fletcher 

#  group :  us 
user : : rwx 

user : spy:  

user : archer : rw- 
group : : r — 

other :  

default : user :  :  rwx 

default : user : spy :  

default : group : : r — 
default : other :  
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NOTICES 

The  output  from  getacl  will  be  in  the  correct  format  for  input  to  the  setacl  command.  If  the  output 
from  getacl  is  redirected  to  a  file,  the  file  may  be  used  as  input  to  setacl.  In  this  way,  a  user  may 
easily  assign  one  file's  ACL  to  another  file. 

FILES 

/etc/passwd  for  user  I  Ds 

/etc/group  for  group  I  Ds 

SEE  ALSO 

ad (2),  aclsort(3C),  chmod(l),  ls(l),  setacl(l). 


HP-UX  Release  Hi:  December  2000 


-3- 


Section  1-327 


getconf(l) 


getconf(l) 


NAME 

getconf  -  get  system  configuration  values 

SYNOPSIS 

getconf  [-v  specification]  systemvar 

getconf  [-v  specification]  system  var  pathname 
DESCRIPTION 

The  getconf  command  provides  an  interface  to  the  confstr(3C),  pathconf(2),  and  sysconf(2)  library  rou- 
tines and  system  calls. 

The  system  var  argument  specifies  the  configuration  value  desired  in  confstr()  ,  pathconf  ()  ,  or 
sysconf  ()  .  Use  the  first  synopsis  form,  for  inquiries  involving  confstr  ()  ,  or  sysconf  ()  (in  the 
first  tablebelow).  Use  the  second  synopsis  form,  for  inquiries  involvingpathconf  ()  (in  the  second  table 
below).  For  inquiries  involvingpathconf  ()  the  pathname  operand  should  be  specified. 

Options 

getconf  recognizes  the  following  option: 

-v  specification     Return  configuration  variables  corresponding  to  a  particular  compilation  environ- 
ment supported  by  HP-UX.  If  the  -v  option  is  not  specified,  specification  defaults 
toXBS5_ILP32_OFF32.  See  table  below  for  possiblespecifications  and  meanings. 
Specification  int     long    pointer  offt 


XBS5 

ILP32  OFF32 

32 

32 

32 

32 

XBS5 

ILP32  OFFBIG 

32 

32 

32 

>=64 

XBS5 

LP64  OFF 64 

32 

64 

64 

64 

XBS5 

LPBIG  OFFBIG 

>=32 

>=64 

>=64 

>=64 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  getconf  behaves  as  if  all  internationali- 
zation variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-byte  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

The  error  codes  returned  by  getconf  are: 

0  Success.  A  value  corresponding  to  the  operand  was  returned. 

1  One  or  more  missing  operands. 

2  Operand  was  not  recognized. 

3  pathname  either  invalid  or  inaccessible. 

EXAMPLES 

Request  the  number  of  intervals  per  second: 

getconf  CLK_TCK 

Request  the  maximum  value  of  a  file's  link  count: 

getconf  LINK_MAX  /etc/passwd 
Other  supported  inquiries  include  the  following: 

ARG_MAX  _BC_BASE_MAX  BC_DIM_MAX 
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BS_SCALE_MAX 
CHAR_BIT 
CHILD_MAX 
CPU_CHIP_TYPE 
CS_PATH 

HW_CPU_SUPP_BITS 
INT_MIN 
LONG_BIT 
MACHINE_IDENT 
MB_LEN_MAX 
NLLANGMAX 
NL_SETMAX 
OPEN_MAX 
_POS IX_ARG_MAX 
_POS IX_OPEN_MAX 
_POSIX_STREAM_MAX 
POSIX_ARG_MAX 
POS IX_LINK_MAX 
POS IX_NAME_MAX 
POS IX_PATH_MAX 
POSIX_SSIZE_MAX 
POSIX_VERSION 
POSIX2_BC_SCALE_MAX 
POSIX2_C_DEV 
POSIX_CHILD_MAX 
POSIX2_FORT_DEV 
POS IX2_LOCALEDEF 
POSIX2_UPE 
SC_XOPEN_VERSION 
SHRT_MAX 
STREAM_MAX 
TZNAME_MAX 
ULONG_MAX 
XOPEN_VERSION 
XOPEN_XPG3 

XBS5_ILP32_OFF32_CFLAGS 
XBS5_ILP32_OFF32_LIBS 
XBS5_ILP32_OFFBIG_CFLAGS 
XBS5_ILP32_OFFBIG_LIBS 
XBS5_LP64_OFF64_CFLAGS 
XBS5_LP64_OFF64_LIBS 


BC_STRING_MAX 
CHAR_MAX 
CLK_TCK 

CS_MACHINE_IDENT 
CS_MACHINE_SERIAL 
HW_32_64_CAPABLE 
KERNEL_BITS 
LONG_MAX 
MACHINE_MODEL 
NGROUPS_MAX 
NL_MSGMAX 
NL_TEXTMAX 
PARTITION_IDENT 
_POSIX_JOB_CONTROL 
_POSIX_SAVED_IDS 
_POSIX_TZNAME_MAX 
POSIX_CHILD_MAX 
POS IX_MAX_CANON 
POSIX_NGROUPS_MAX 
POSIX_PIPE_BUF 
POSIX_STREAM_MAX 
POSIX2  BC  BASE  MAX 


POSIX2_BC_STRING_MAX 
POSIX2_C_VERSION 
POSIX2_COLL_WEIGHTS_MAX 
POSIX2_FORT_RUN 
POSIX2_RE_DUP_MAX 
POSIX2_VERSION 
SCHAR_MAX 
SHRT_MIN 
RE_DUP_MAX 
UCHAR_MAX 
USHRT_MAX 
XOPEN_XCU_VERS ION 
XOPEN_XPG4 

XBS5_ILP32_OFF32_LDFLAGS 
XBS5_ILP32_OFF32_LINTFLAGS 
XBS5_ILP32_OFFBIG_LDFLAGS 
XBS5_ILP32_OFFBIG_LINTFLAGS 
XBS5_LP64_OFF64_LDFLAGS 
XBS5_LP64_OFF64_LINTFLAGS 


CHARCLAS  S_NAME_MAX 
CHAR_MIN 

COLL_WE IGHT S_MAX 

C  S_P ART I T I ON_I DENT 

EXPR_NEST_MAX 

INT_MAX 

LINE_MAX 

LONG_MIN 

MACHINE_SERIAL 

NL_ARGMAX 

NL_NMAX 

NZERO 

PATH 

_POSIX_NGROUPS_MAX 
_POS IX_SS I ZE_MAX 
_POSIX_VERSION 
POSIX_JOB_CONTROL 
POSIX_MAX_INPUT 
POS IX_OPEN_MAX 
POSIX_SAVED_IDS 
POSIX_TZNAME_MAX 
POSIX2_BC_DIM_MAX 
POSIX2_C_BIND 
POS IX2_CHAR_TERM 
POSIX2_EXPR_NEST_MAX 
POSIX2_LINE_MAX 
POSIX2_SW_DEV 
SC_PASS_MAX 
SCHAR_MIN 
SSIZE_MAX 
TMP_MAX 
UINT_MAX 
WORD_BIT 
XOPEN  XPG2 


Supported  inquiries requiringthe second  parameter  include: 


MAX_INPUT 
PIPE_BUF 

_POS IX_MAX_CANON 
_POS IX_NAME_MAX 
_POSIX_VDISABLE 
POSIX_VDISABLE 

AUTHOR 

getconf  was  developed  by  HP  andPOSIX. 

SEE  ALSO 

pathconf(2),  sysconf(2),  confstr(3C). 

STANDARDS  CONFORMANCE 

getconf:  POSIX.2,  XPG4 


LINK_MAX  MAXCANON 

NAME_MAX  PATH_MAX 

_POSIX_CHOWN_RESTRICTED  _POSIX_LINK_MAX 

_POSIX_MAX_INPUT  _POSIX_NO_TRUNC 

_POSIX_PATH_MAX  _POSIX_PIPE_BUF 

POSIX  CHOWN  RESTRICTED  POSIX  NO  TRUNC 
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NAME 

getopt  -  parse  command  options 

SYNOPSIS 

getopt  optstring  args 

DESCRIPTION 

getopt  is  used  to  break  up  options  in  command  lines  for  easy  parsing  by  shell  procedures  and  to  check  for 
legal  options,  optstring  is  a  string  of  recognized  option  letters  (see  getopt(3C)).  If  a  letter  is  followed  by  a 
colon,  the  option  is  expected  to  have  an  argument  which  may  or  may  not  be  separated  from  it  by  white 
space. 

The  positional  parameters  ($1  $2  ... )  of  the  shell  are  reset  so  that  each  option  is  preceded  by  a  -  and  is  in 
its  own  positional  parameter;  each  option  argument  is  also  parsed  into  its  own  positional  parameter. 

getopt  recognizes  two  hyphens  (--)  to  delimit  the  end  of  the  options.  If  absent,  getopt  places  — at 
the  end  of  the  options. 

The  most  common  use  of  getopt  is  in  the  shell's  set  command  (see  the  example  below)  where 
getopt  converts  the  command  line  to  a  more  easily  parsed  form,  getopt  writes  the  modified  com- 
mand line  to  the  standard  output. 

EXTERNAL  INFLUENCES 
Envi  ronment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable. 

If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 
If  any  internationalization  variable  contains  an  invalid  setting,  getopt  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  envi  ran  (5). 

I  nternational  Code  Set  Support 

Single-byte  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

getopt  prints  an  error  message  on  the  standard  error  when  it  encounters  an  option  letter  not  included  in 
optstring. 

EXAMPLES 

The  foil  owing  code  fragment  processes  the  arguments  for  a  command  that  can  take  the  options  a  or  b,  and 
the  option  o  which  requires  an  argument: 

set  —   'getopt  abo:   $* 1 

if   [  $?  -ne  0  ] ;  then 
echo  $USAGE 
exit  2 

fi 

while    [  $#  -gt  0  ] ;  do 
case  $1  in 
-a   I  -b) 

FLAG=$1 

shift 

/  f 

-o) 

OARG=$2 

shift  2 

/  f 

— ) 

shift 
break 

esac 
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done 

This  code  accepts  any  of  the  following  as  equivalent: 

cmd  -aoarg  file  file 
cmd  -a  -o  arg  file  file 
cmd  -oarg  -a  file  file 
cmd  -a  -oarg  —  file  file 

WARNINGS 

getopt  option  arguments  must  not  be  null  strings  nor  contain  embedded  blanks. 

SEE  ALSO 

sh(l),  getopt(3C). 
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NAME 

getopts  -  parse  utility  (command)  options 

SYNOPSIS 

getopts  optstring  name  [arg  ...] 

DESCRIPTION 

getopts  is  used  to  retrieve  options  and  option-arguments  from  a  list  of  parameters. 

Each  time  it  is  invoked,  getopts  places  the  value  of  the  next  option  in  the  shell  variable  specified  by  the 
name  operand  and  the  index  of  the  next  argument  to  be  processed  in  the  shell  variable OPTIND.  When- 
ever the  shell  is  invoked,  OPTIND  is  initial ized  to  1. 

When  the  option  requires  an  option-argument,  getopts  places  it  in  the  shell  variable  OPTARG.  If  no 
option  was  found,  or  if  the  option  that  was  found  does  not  have  an  option-argument,  OPTARG  is  unset. 

If  an  option  character  not  contained  in  the  optstring  operand  is  found  where  an  option  character  is 
expected,  the  shell  variable  specified  by  nameisset  to  the  question-mark  (?)  character.  In  thiscase,  if  the 
first  character  in  optstring  is  a  colon  (:),  the  shell  variable  OPTARG  is  set  to  the  option  character  found, 
but  no  output  is  written  to  standard  error;  otherwise,  the  shell  variable  OPTARG  is  unset  and  a  diagnostic 
message  is  written  to  standard  error.  This  condition  is  considered  to  be  an  error  detected  in  the  way  argu- 
ments were  presented  to  the  invoking  application,  but  is  not  an  error  in  getopts  processing. 

If  an  option-argument  is  missing: 

•  If  the  first  character  of  optstring  is  a  colon,  the  shell  variable  specified  by  name  is  set  to  the  colon 
character  and  the  shell  variable  OPTARG  is  set  to  the  option  character  found. 

•  Otherwise,  the  shell  variable  specified  by  name  is  set  to  the  question-mark  character,  the  shell 
variable  OPTARG  is  unset,  and  a  diagnostic  message  is  written  to  the  standard  error.  This  condi- 
tion is  considered  to  be  an  error  detected  in  the  way  arguments  are  presented  to  the  invoking 
application,  but  is  not  an  error  in  getopts  processing;  a  diagnostic  message  is  written  as  stated, 
but  the  exit  status  is  zero. 

When  the  end  of  options  is  encountered,  getopts  exits  with  a  return  value  greater  than  zero.  The  shell 
variable  OPTIND  is  set  to  the  index  of  the  first  nonoption-argument,  where  the  first  —  argument  is  con- 
sidered to  be  an  option  argument  if  there  are  no  other  non-option  arguments  appearing  before  it,  or  the 
value  $#  + 1  if  there  are  no  nonoption-arguments;  the  name  variable  is  set  to  the  question-mark  character. 
Any  of  the  foil  owing  identifies  the  end  of  options:  the  special  option  — ,  finding  an  argument  that  does  not 
begin  with  a  -,  or  encountering  an  error. 

The  shell  variables  OPTIND  and  OPTARG  are  local  to  the  caller  of  getopts  and  are  not  exported  by 
default. 

Theshell  variable  specified  by  the  name  operand,  OPTIND,  and  OPTARG  affect  the  current  shell  execution 
environment. 


Operands 

The  foil  owing  operands  are  supported: 

optstring  A  string  containing  the  option  characters  recognized  by  the  utility  invoking 
getopts.  If  a  character  is  followed  by  a  colon  (:),  the  option  will  be  expected  to 
have  an  argument,  which  should  be  supplied  as  a  separate  argument.  Applications 
should  specify  an  option  character  and  its  option-argument  as  separate  arguments, 
but  getopts  will  interpret  the  characters  following  an  option  character  requiring 
arguments  as  an  argument  whether  or  not  this  is  done.  An  explicit  null  option- 
argument  need  not  be  recognised  if  it  is  not  supplied  as  a  separate  argument  when 
getopts  is  invoked.  The  characters  question-mark  (?)  and  colon  (:)  must  not  be 
used  as  option  characters  by  an  application.  The  use  of  other  option  characters  that 
are  not  alphanumeric  produces  unspecified  results.  If  the  option-argument  is  not  sup- 
plied as  a  separate  argument  from  the  option  character,  the  val ue  i n  OPTARG  will  be 
stripped  of  the  option  character  and  the-.  Thefirst  character  in  optstring  will  deter- 
mine how  getopts  will  behave  if  an  option  character  is  not  known  or  an  option- 
argument  is  missing. 

name  The  name  of  a  shell  variablethat  is  set  by  getopts  to  the  option  character  that  was 

found. 
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getopts  by  default  parses  positional  parameters  passed  to  the  invoking  shell  procedures.  If  args  are 
given,  they  are  parsed  instead  of  the  positional  parameters. 

EXTERNAL  INFLUENCES 
Environment  Variable 

Thefollowing  environment  variable  affects  the  execution  of  the  getopts  utility: 

OPTIND         Used  by  getopts  as  the  index  of  the  next  argument  to  be  processed. 

ERRORS 

Whenever  an  error  is  detected  and  the  first  character  in  the  optstring  operand  is  not  a  colon  ( : ),  a  diagnos- 
tic message  will  be  written  to  standard  error  with  thefollowing  information  in  an  unspecified  format: 

•  The  invoking  program  name  will  be  identified  in  the  message.  The  invoking  program  name  will  be 
the  value  of  the  shell  special  parameter  0  at  the  time  the  getopts  utility  is  invoked.  A  name 
equivalent  to: 

basename  "$0" 

may  be  used. 

•  If  an  option  is  found  that  was  not  specified  in  optstring,  this  error  will  be  identified  and  the  invalid 
option  character  will  be  identified  in  the  message. 

•  If  an  option  requiring  an  option-argument  is  found,  but  an  option-argument  is  not  found,  this  error 
will  be  identified  and  the  invalid  option  character  will  be  identified  in  the  message. 

EXAMPLES 

Since  getopts  affects  the  current  shell  execution  environment,  it  is  generally  provided  as  a  shell  regular 
built-in.  If  it  is  cal led  in  a  subshell  or  separate  utility  execution  environment  such  as  one  of  thefollowing: 

(getopts  abc  value  "$@") 
nohup  getopts    . . . 
find  -exec  getopts  ...\; 

it  does  not  affect  the  shell  variables  in  the  caller's  environment. 

Note  that  shell  functions  share  OPTIND  with  the  calling  shell  even  though  the  positional  parameters  are 
changed.  Functions  that  use  getopts  to  parse  their  arguments  should  save  the  value  of  OPTIND  on 
entry  and  restore  it  before  returning.  However,  there  will  be  cases  when  a  function  must  change  OPTIND 
for  the  calling  shell. 

Thefollowing  example  script  parses  and  displays  its  arguments: 

aflag= 
bflag= 

while  getopts  ab :  name 
do 

case  $name  in 
a) 

aflag=l; ; 

b) 

bflag=l 

bval="$OPTARG" ;  ; 

?) 

printf   "Usage:    %s :    [-a]    [-b  value]    args\n"  $0 
exit  2 ; ; 

esac 

done 

if   [   !  -z  "$aflag"   ]    ;  then 

printf  "Option  -a  specified\n" 

fi 

if   [    !   -z   "$bflag"    ]    ;  then 

printf   "Option  -b  "%s"   specified\n"  "$bval" 

fi 

shift   $(($OPTIND  -1)) 

printf   "Remaining  arguments  are:    %s\n"  "$*" 
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SEE  ALSO 

getopt(l),  ksh(l),  sh-posix(l),  sh(l),  getopt(3C). 

STANDARDS  CONFORMANCE 

getopts:  XPG4,  POSIX.2 
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NAME 

getprivgrp  -  get  special  attri butes for  group 

SYNOPSIS 

getprivgrp  [-g  |  group  name] 

DESCRIPTION 

getprivgrp  lists  the  access  privileges  of  privileged  groups  set  by  setprivgrp  (see  setprivgrp(lM)). 
If  group  name  is  supplied,  access  privileges  are  listed  for  that  group  only.  If  the  caller  is  not  a  member  of 
group  name,  no  information  is  displayed.  If  -g  is  used,  getprivgrp  lists  access  privileges  that  have 
been  granted  to  all  groups.  Otherwise,  access  privileges  are  listed  for  all  privileged  groups  to  which  the 
caller  belongs. 

The  super-user  is  a  member  of  all  groups.  Access  privileges  includeRTPRlO,  RTSCHED,  MLOCK,  CHOWN, 

LOCKRDONLY,  SETRUGID, and  SERIALIZE. 

AUTHOR 

getprivgrp  was  developed  by  HP. 

SEE  ALSO 

setprivgrp(lM),  getprivgrp(2),  privgrp(4). 
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NAME 

gprof  -  display  call  graph  profile  data 
SYNOPSIS 

gprof  [options]  [a. out  [gmon.out ...  ]]  [shared  l ibrary  shared  l ibrary  profile] 
DESCRIPTION 

The  gprof  command  produces  an  execution  profile  of  C++,  C,  Pascal,  and  FORTRAN  programs.  The 
effect  of  called  routines  is  incorporated  into  the  profile  of  each  caller.  Profile  data  is  taken  from  the  call 
graph  profile  file  (gmon .  out  default)  that  is  created  by  programs  compiled  with  the-G  option  of  aCC,  CC, 
cc,  pc,  and  f  77.  That  option  also  links  in  versions  of  the  library  routines  that  are  compiled  for  profiling. 
The  symbol  table  in  the  named  object  file  (a.  out  default)  is  read  and  correlated  with  the  call  graph  profile 
file.  If  more  than  one  profile  file  is  specified,  gprof  output  shows  the  sum  of  the  profile  information  in  the 
given  profile  files. 

First,  a  flat  profile  is  given,  similar  to  that  provided  by  prof  (see  prof(l)).  This  listing  gives  the  total  exe- 
cution times  and  call  counts  for  each  function  in  the  program,  sorted  by  decreasing  time. 

Next,  these  times  are  propagated  along  the  edges  of  the  call  graph,  gprof  discovers  all  cycles  in  the  call 
graph.  All  calls  made  into  the  cycle  share  the  time  of  that  cycle.  A  second  listing  shows  the  functions 
sorted  according  to  the  time  they  represent  including  the  time  of  their  call  graph  descendants.  Below  each 
function  entry  is  shown  its  (direct)  call  graph  children,  and  how  their  times  are  propagated  to  this  function. 
A  similar  display  above  the  function  shows  how  the  time  of  this  function  and  the  time  of  its  descendants  are 
propagated  to  its  (direct)  call  graph  parents. 

Cycles  are  also  shown,  with  an  entry  for  the  cycle  as  a  whole  and  a  listing  of  the  members  of  the  cycle,  each 
with  their  contributions  to  the  time  and  call  counts  of  the  cycle. 

Shared  Library  Profiling  (32-bit  only) 

Support  for  gprof  profiling  of  shared  libraries  is  availableon  32-bit  systems  only. 

To  profile  shared  libraries,  set  the  environment  variable  LD_PR0FILE  to  the  path  of  the  shared  library  to 
be  profiled.  (See  HP-UX  Linker  and  Libraries  Online  User's  Guidefor  details.)  Do  not  use  the  -G  option  to 
compile  programs  for  shared  libraries  profiling.  Do  not  link  the  executable  gcrtO.o  or  mcrtO.o.  This 
turns  on  profiling  of  a. out,  which  is  not  compatible  with  profiling  of  shared  libraries.  You  can  either 
profileyour  executableor  a  shared  library,  but  not  both. 

At  the  termination  of  the  program,  a  profile  file  with  the  name  of  the  shared  library  prepended  to  it  is  gen- 
erated by  a  run-time  library.  To  get  the  complete  listing,  provide  the  gprof  command  with  names  of  the 
shared  library  and  the  profile  file  for  the  shared  library  as  arguments. 

Options 

Thegprof  command  recognizes  the  following  options: 


-a 


Suppress  printing  statically  declared  functions.  If  this  option  is  given,  all  relevant 
information  about  the  static  function  (such  as  time  samples,  calls  to  other  functions, 
and  calls  from  other  functions)  belongs  to  the  function  loaded  just  before  the  static 
function  in  the  a .  out  file. 


-b 


Suppress  printing  a  description  of  each  field  in  the  profile. 


-e  name 


Suppress  printing  the  graph  profile  entry  for  routine  name  and  all  its  descendants 
(unless  they  have  other  ancestors  that  are  not  suppressed).  More  than  one  -e  option 
can  be  given.  Only  one  name  can  be  given  with  each  -e  option. 


-E  name 


Suppress  printing  the  graph  profile  entry  for  routine  name  (and  its  descendants)  as  - 
e  above,  and  also  exclude  the  time  spent  in  name  (and  its  descendants)  from  the  total 
and  percentage  time  computations.    -E  mcount  -E  mcleanup  is  the  default. 


-f  name 


Print  only  the  graph  profile  entry  of  the  specified  routine  name  and  its  descendants. 
More  than  one  -f  option  can  be  given.  Only  one  name  can  be  given  with  each  -f 
option. 


-F  name 


Print  only  the  graph  profile  entry  of  the  routine  name  and  its  descendants  (as  -f 
above)  and  also  use  only  the  times  of  the  printed  routines  in  total  time  and  percentage 
computations.  More  than  one  — F  option  can  be  given.  Only  one  name  can  be  given 
with  each  -F  option.  The  -F  option  overrides  the  -E  option. 
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-s  Produce  a  profilefilegmon .  sum  that  represents  the  sum  of  the  profile  information  in 

all  specified  profile  files.  This  summary  profile  file  can  be  given  to  subsequent  execu- 
tions of  gprof  (probably  also  with  a  -s  option)  to  accumulate  profile  data  across 
several  runs  of  an  a .  out  file. 

-z  Display  routines  that  have  zero  usage  (as  indicated  by  call  counts  and  accumulated 

time). 

The  name  of  the  file  created  by  a  profiled  program  is  controlled  by  the  environment  variable  GPROFDIR. 
If  GPROFDIR  is  not  set,  gmon .  out  is  produced  in  the  current  directory  when  the  program  terminates.  If 
GPROFDlR=string,  string/ pi d.progname  is  produced,  where  progname  consists  of  argv[0]  with  any 
path  prefix  removed,  and  pid  is  the  program's  process  ID.  If  GPROFDIR  is  set  to  a  null  string,  no  profiling 
output  is  produced. 

EXAMPLES 

To  profilelibc.sl: 

$  cat  >  test . c 

main ( ) 

{ 

printf ( "hello  world\n") ; 
} 

$  cc  test . c  -lc 

$  ldd  a. out 

/usr/l  i  b/l  i  bc.2  =>  /usr/l  i  b/l  i  bc.2 
/usr/lib/libdld.2  =>  /usr/lib/libdld.2 

/usr/l  i  b/l  i  bc.2  =>  /usr/l  i  b/l  i  bc.2 

$  export  LD_PROFILE=/usr/lib/libc.2 

$   ./a. out 
hello  world 

$  unset  LD_PROFILE 

$  Is  libc . 2 .prof ile 

libc.2.profile 

$  11  libc . 2 .prof ile 

-rw-rw-r-   1  userl      lang       606464May  19  10:24  libc.2.profile 
$  gprof  /usr/lib/libc . 2  libc . 2 . prof ile 

WARNINGS 

Beware  of  quantization  errors.  The  granularity  of  the  sampling  is  shown,  but  remains  statistical  at  best.  It 
is  assumed  that  the  time  for  each  execution  of  a  function  can  be  expressed  by  the  total  time  for  the  func- 
tion, divided  by  the  number  of  times  the  function  is  called.  Thus  the  time  propagated  along  the  call  graph 
arcs  to  parents  of  that  function  is  directly  proportional  to  the  number  of  times  that  arc  is  traversed. 

Parents  that  are  not  profiled  have  the  time  of  their  profiled  children  propagated  to  them,  but  they  appear  to 
be  spontaneously  invoked  in  the  call  graph  listing,  and  do  not  have  their  time  propagated  further.  Simi- 
larly, signal  catchers,  even  though  profiled,  appear  to  be  spontaneous  (although  for  more  obscure  reasons). 
Any  profiled  children  of  signal  catchers  should  have  their  times  propagated  properly  unless  the  signal 
catcher  was  invoked  during  the  execution  of  the  profiling  routine,  in  which  case  all  is  lost. 

The  profiled  program  must  call  exit  ()  (see  exit(2))  or  return  normally,  for  the  profiling  information  to  be 
saved  in  the  gmon .  out  file. 

Thefollowing  limitations  exist  for  gprof  shared  library  profiling: 

•  Local,  static,  and  hidden  functions  are  not  profiled. 

•  Shared  libraries  built  with  -B  symbolic  are  not  profiled. 

•  Any  function  calls  made  from  library  initializers  are  not  collected. 

Set  LD_PROFlLE  to  the  exact  string  with  which  you  call  shl_load.  If  the  library  is  implicitly  loaded, 
LD_PR0FILE  must  match  the  path  encoded  i n  the  a .  out .  You  can  find  this  value  by  running  the  ldd 
command  on  the  executable. 
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DEPENDENCIES 

gprof  cannot  be  used  with  dynamically  linked  executables  (built  with  Id  -A  in  pre  HP-UX  10.20 
releases). 

AUTHOR 

gprof  was  developed  by  the  University  of  California,  Berkeley. 
FILES 

a. out*  Default  object  file, 

gmon .  out*  Default  dynamic  call  graph  and  profile, 

gmon.  sum*  Summarized  dynamic  call  graph  and  profile, 

/usr/lib/gprof .  callg*  Call  graph  description, 

/usr/lib/gprof .  flat*  Flat  profile  description, 

/usr/lib/libgprof  32  .  si  gprof  32-bit  shared  library  profiler 

SEE  ALSO 

ccbundled(l),  prof(l),  exit(2),  profil(2),  crt0(3),  monitor(3C). 

gprof:  A  Call  Graph  Execution  Profiler;  Graham,  S.L.,  Kessler,  P.B.,  McKusick,  M.K.; 

Proceedings  of  the SIGPLAN  '82  Symposium  on  Compiler  Construction;  SIGPLAN  Notices;  Vol.  17,  No.  6, 
pp.  120-126,  J  unel982. 

HP-UX  Linker  and  Libraries OnlineUser's  Guide(See the  Id  +help  option). 
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NAME 

grep,  egrep,  fgrep  -  search  a  file  for  a  pattern 

SYNOPSIS 

Plain  call  with  pattern 

grep  [-E  | -F]  [-c|-l|-q]  [-bhinsvwx]  pattern  [file  ...] 

Call  with  (multiple)  -e  pattern 

grep  [-E  | -F]  [-c|-l]-q]  [-bhinsvwx]  -e  pattern...    [-e  pattern]  ...    [file  ...] 

Call  with  -f  file 

grep  [-E  | -F]  [-c|-l|-q]  [-bhinsvwx]  [-f  patternfile]  [file  ...] 

Obsolescent: 

egrep  [-cefilnsv]  [expression]  [file  ...] 

fgrep  [-cefilnsvx]  [strings]  [file  ...] 
DESCRIPTION 

The  grep  command  searches  the  input  text  files  (standard  input  default)  for  lines  matching  a  pattern. 
Normally,  each  line  found  is  copied  to  the  standard  output,  grep  supports  the  Basic  Regular  Expression 
syntax  (see  regexp(5)).  The  -E  option  (egrep)  supports  Extended  Regular  Expression  (ERE)  syntax  (see 
regexp(5)).  The  -F  option  (fgrep)  searches  for  fixed  strings  using  the  fast  Boyer-Moore  string  searching 
algorithm.  The  -E  and  -F  options  treat  newlines  embedded  in  the  pattern  as  alternation  characters.  A 
null  expression  or  string  matches  every  line. 

The  forms  egrep  and  fgrep  are  maintained  for  backward  compatibility.  The  use  of  the  -E  and  -F 
options  is  recommended  for  portability. 

Options 

-E  Extended  regular  expressions.  Each  pattern  specified  is  a  sequence  of  one  or 

more  EREs.  The  EREs  can  be  separated  by  newline  characters  or  given  in 
separate -e  expression  options.  A  pattern  matches  an  input  line  if  any  ERE  in 
the  sequence  matches  the  contents  of  the  input  line  without  its  trailing  newline 
character.  Thesame  functionality  isobtained  by  using  egrep. 

-F  Fixed  strings.  Each  pattern  specified  is  a  sequence  of  one  or  more  strings. 

Strings  can  be  separated  by  newline  characters  or  given  in  separate  -e  expres- 
sion options.  A  pattern  matches  an  input  line  if  the  line  contains  any  of  the 
strings  in  the  sequence.  The  same  functionality  is  obtained  by  using  fgrep. 

-b  Each  line  is  preceded  by  the  block  number  on  which  it  was  found.  This  is  useful 

in  locating  disk  block  numbers  by  context.  Block  numbers  are  calculated  by 
dividing  by  512  the  number  of  bytes  that  have  been  read  from  the  file  and  round- 
ing down  the  result. 

-c  Only  a  count  of  matching  lines  is  printed. 

-e  expression  Same  as  a  simple  expression  argument,  but  useful  when  the  expression  begins 

with  a  hyphen  (-).  Multiple-e  options  can  be  used  to  specify  multiple  patterns; 
an  input  line  is  selected  if  it  matches  any  of  the  specified  patterns. 

-f  patternfile       The  regular  expression  (grep  and  grep  -E)  or  strings  list  (grep  -F)istaken 
from  the  pattern  file. 

-h  Suppress  printing  of  filenames  when  searching  multiplexes. 

-i  Ignore  uppercase/lowercase  distinctions  during  comparisons. 

-1  Only  the  names  of  files  with  matching  lines  are  listed  (once),  separated  by  new- 

lines.  If  standard  input  is  searched,  a  path  name  of  (standard  input)  will 
be  written,  in  the  POSIX  locale.  I  n  other  locales,  (standard  input)  maybe 
replaced  by  something  more  appropriate  in  those  locales. 

-n  Each  line  is  preceded  by  its  relative  line  number  in  the  file  starting  at  1.  The 

line  number  is  reset  for  each  file  searched.  This  option  is  ignored  if  -c,  -b,  -1, 
or  -q  is  specified. 
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-q 


(Quiet)  Do  not  write  anything  to  the  standard  output,  regardless  of  matching 
lines.  Exit  with  zero  status  upon  finding  the  first  matching  line.  Overrides  any 
options  that  would  produce  output. 


-s 


Error  messages  produced  for  nonexistent  or  unreadablefiles  are  suppressed. 


-v 


All  lines  but  those  matching  are  printed. 


-w 


Select  only  those  lines  containing  matches  that  form  whole  words.  The  test  is 
that  the  matching  substring  must  either  be  at  the  beginning  of  the  line,  or  pre- 
ceded by  a  non-word  constituent  character.  Similarly,  it  must  be  either  at  the 
end  of  the  line  or  followed  by  a  non-word  constituent  character.  Word-constituent 
characters  are  letters,  digits,  and  the  underscore. 


-x 


(eXact)  Matches  are  recognized  only  when  the  entire  input  line  matches  the  fixed 
string  or  regular  expression. 


The  file  name  is  output  in  all  the  cases  in  which  output  is  generated  if  there  are  more  than  one  input  file, 
unless  the -h  option  is  specified.  Care  should  betaken  when  using  the  characters  $,  *,  [,",  |,  (,),and\ 
in  expression,  because  they  are  also  meaningful  to  the  shell.  It  is  safest  to  enclose  the  entire  expression 
argument  in  singlequotes  (' ). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  C  (see  lang(5))  is  used. 

LC_ALL  determines  thelocaleto  use  to  override  any  values  for  locale  categories  specified  by  the  setti  ngs  of 
LANG  or  any  environment  variables  beginning  with  LC_. 

LC_COLLATE  determines  the  collating  sequence  used  in  evaluating  regular  expressions. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  byte  and/or  multi-byte  characters,  the 
classification  of  characters  as  letters,  the  case  information  for  the  -i  option,  and  the  characters  matched 
by  character  class  expressions  in  regular  expressions. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  any  internationalization  variable  contains  an  invalid  setting,  the  commands  behave  as  if  all  international- 
ization variables  are  set  toe.  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-byte  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

Upon  completion,  grep  returns  one  of  the  foil  owing  values: 


EXAMPLES 

I  n  the  Bourne  shell  (sh(l))  the  following  example  searches  two  files,  finding  all  lines  containing  occurrences 
of  any  of  four  strings: 

grep  -F  'if 

then 

else 

fi'  filel file2 

Note  that  the  single  quotes  are  necessary  to  tell  grep  — F  when  the  strings  have  ended  and  the  file  names 
have  begun. 

For  the  C  shell  (see  csh(l))  the  foil  owing  command  can  be  used: 

grep  -F  '  if  \     then\     else\  fi'    filel  file2 
To  search  a  file  named  address  containing  the  foil  owing  entries: 


Section  1-340  -  2  -  HP-UX  Release  Hi :  December  2000 


0  One  or  more  matches  found. 

1  No  match  found. 

2  Syntax  error  or  inaccessiblefile  (even  if  matches  were  found). 


grep(l) 


grep(l) 


Ken       112  Warring  St.     Apt.  A 
Judy     387  Bowditch     Apt .  12 
Ann       429  Sixth  St. 

the  command: 

grep  Judy  address 

prints: 

Judy     387  Bowditch     Apt .  12 

To  search  a  file  for  lines  that  contain  either  a  Dec  or  Nov,  use  either  of  the  foil  owing  commands: 

grep  -E  '  [Dd]  ec  |  [Nn]ov'  file 
egrep  -i  'dec|nov'  file 

Search  all  files  in  the  current  directory  for  the  string  xyz: 

grep  xyz  * 

Search  all  files  in  the  current  directory  subtree  for  the  string  xyz,  and  ensure  that  no  error  occurs  due  to 
file  name  expansion  exceeding  system  argument  list  limits: 

find   .   -type  f  -print    | xargs  grep  xyz 

The  previous  example  does  not  print  the  name  of  files  where  string  xyz  appears.  To  force  grep  to  print 
filenames,  add  a  second  argument  to  the  grep  command  portion  of  the  command  line: 

find   .   -type  f  -print    | xargs  grep  xyz  /dev/null 

I  n  this  form,  the  first  file  name  is  that  produced  by  find,  and  the  second  file  name  is  the  null  file. 

WARNINGS 

(XPG4  only.)  If  the  -q  option  is  specified,  the  exit  status  will  be  zero  if  an  input  line  is  selected,  even  if  an 
error  was  detected.  Otherwise,  default  actions  will  be  performed. 

If  the  -w  option  is  specified  with  non-word  constituent  characters,  then  the  output  is  unexpected. 
SEE  ALSO 

sed(l),  sh(l),  regcomp(3C),  environ(5),  lang(5),  regexp(5). 

STANDARDS  CONFORMANCE 

grep:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 

egrep:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
fgrep:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

groups  -  show  group  memberships 

SYNOPSIS 

groups  [-p]  [-g]  [-1]  [user] 

DESCRIPTION 

groups  shows  the  groups  to  which  the  caller  or  the  optionally  specified  user  belong.  If  invoked  with  no 
arguments,  groups  prints  the  current  access  list  returned  by  getgroups()  (see  getgroups(2)). 

Each  user  belongs  to  a  group  specified  in  the  password  file  /etc/passwd  and  possibly  to  other  groups  as 
specified  in  the  files  /etc/group  and /etc/logingroup.  A  user  is  granted  the  permissions  of  those 
groups  specified  in  /etc/passwd  and  /etc/logingroup  at  login  time.  The  permissions  of  the 
groups  specified  in  /etc/group  are  normally  availableonly  with  the  useof  newgrp  (see  newgrp(l)).  If 
a  user  name  is  specified  with  no  options,  groups  prints  the  union  of  all  these  groups. 

The  -p,  -g,  and  -1  options  limit  the  printed  list  to  those  groups  specified  in  /etc/passwd, 
/etc/group,  and  /etc/logingroup,  respectively.  If  a  user  name  is  not  specified  with  any  of  these 
options,  cuserid()  is  cal  led  to  determine  the  default  user  name  (see  cuserid(3S)). 

The  printed  list  of  groups  is  sorted  in  ascending  collation  order  (see  Environment  Variables  below). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  order  in  which  the  output  is  sorted. 

If  LC_COLLATE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is 
used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid  setting,  groups  behaves  as 
if  all  internationalization  variables  are  set  to  "C"  (see  environ  (5)). 

EXAMPLES 

Check  file  /etc/logingroup  and  display  all  groups  to  which  user  tim  belongs: 
groups  -1  tim 

AUTHOR 

groups  was  developed  by  the  University  of  California,  Berkeley. 

FILES 

/etc /group 
/etc/ logingroup 
/etc/passwd 

SEE  ALSO 

id(l),  newgrp(l),  getgroups(2),  initgroups(3C),  cuserid(3S),  group(4). 
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NAME 

head  -  give  first  few  lines 

SYNOPSIS 

head  [-c|-l]  [-n  count]  [file  ...] 

Obsolescent: 

head  [-count]  [file  ...] 

DESCRIPTION 

head  prints  on  standard  output  the  first  count  lines  of  each  of  the  specified  files,  or  of  the  standard  input. 
If  count  is  omitted  it  defaults  to  10. 

If  multiple  files  are  specified,  head  outputs  before  each  file  a  line  of  this  form: 
==>  file  <== 

Options 

-c  The  quantity  of  output  ismeasured  in  bytes. 

-count  The  number  of  units  of  output.  This  option  is  provided  for  backward  compatibility  (see  -n 

below)  and  ismutuallyexclusiveof  all  other  options. 

-1  The  quantity  of  output  ismeasured  in  lines;  this  is  the  default. 

-n  count  The  number  of  lines  (default)  or  bytes  output,  count  is  an  unsigned  decimal  integer.  If  -n 
(or  -count)  is  not  given,  the  default  quantity  is  10.  This  option  provides  the  same  func- 
tionality as  the  -count  option,  but  in  a  more  standard  way.  Use  of  the  -n  option  is  recom- 
mended where  portability  between  systems  is  important. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  within  file  as  si ngleand/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  head  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

WARNINGS 

The  length  of  the  input  lines  is  limited  to  {LINE_MAX} bytes. 

SEE  ALSO 

tail (1),  cat(l),  more(l),  pg(l). 

STANDARDS  CONFORMANCE 

head:  SVID3,  XPG4,  POSIX.2 
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NAME 

hostname  -  set  or  display  name  of  current  host  system 

SYNOPSIS 

hostname  [nameofhost] 

DESCRIPTION 

The  hostname  command  displays  the  name  of  the  current  host,  as  given  in  the  gethostname  ( )  sys- 
tem call  (see  gethostname(2)).  Users  who  have  appropriate  privileges  can  set  the  hostname  by  giving  the 
argument  name  of  host;  this  is  usually  done  in  the  startup  script  /sbin/init .  d/hostname.  The 
name  of  host  argument  is  restricted  to maxhostnamelen  characters  as  defined  in  <sys/param.  h>. 

The  system  might  be  known  by  other  names  if  networking  products  are  supported.  See  the  node  manager 
documentation  supplied  with  your  system. 

WARNINGS 

If  the  name  of  host  argument  is  specified,  the  resulting  host  name  change  lasts  only  until  the  system  is 
rebooted.  To  change  the  host  name  permanently,  run  the  special  initialization  script  /sbin/set_parms 
(see  Using  Your  HP  Workstation). 

Many  types  of  networking  services  are  supported  on  HP-UX,  each  of  which  uses  a  separately  assigned  sys- 
tem name  and  naming  convention.  To  ensure  predictable  system  behavior,  it  is  essential  that  system 
names  (also  called  host  names  or  node  names)  be  assigned  in  such  a  manner  that  they  do  not  create 
conflicts  when  the  various  networking  facilities  interact  with  each  other. 

The  system  does  not  rely  on  a  single  system  name  in  a  specific  location,  partly  because  different  services 
use  dissimilar  name  formats  as  explained  below.  The  hostname  and  uname  commands  assign  system 
names  as  follows: 


Node  Name 

Command 

name  Format 

Used  By 

1  nternet  name 
UUCP  name 

hostname  name 

uname  -s  name 

sys[.x.y.z...] 
sys 

ARPA  and  NFS  Services 
uucp  and  related  programs 

where  sys  represents  the  assigned  system  name.  It  is  strongly  recommended  that  sys  be  identical  for  all 
commands  and  locations  and  that  the  optional  .x.y.z...  follow  the  specified  notation  for  the  particular 
ARPA/NFS  environment. 

Internet  names  are  also  frequently  called  host  names  or  domain  names  (which  are  different  from  NFS 
domain  names).  Refer  to  hostname(5)  for  more  information  about  I  nternet  naming  conventions. 

Whenever  the  system  name  is  changed  in  any  file  or  by  the  use  of  any  of  the  above  commands,  it  should 
also  be  changed  in  all  other  locations  as  well.  Other  files  or  commands  in  addition  to  those  above  (such  as 
/etc/uucp/Permissions  if  used  to  circumvent  uname,  for  example)  may  contain  or  alter  system 
names.  To  ensure  correct  operation,  they  should  also  use  the  same  system  name. 

System  names  are  normally  assigned  by  the  /sbin/init .  d/hostname  script  at  start-up,  and  should 
not  be  altered  elsewhere. 

AUTHOR 

hostname  was  developed  by  the  University  of  California,  Berkeley. 
SEE  ALSO 

uname(l),  gethostname(2),  sethostname(2),  uname(2),  hostname(5). 
Using  Your  HP  Workstation 
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NAME 

hp  -  handle  special  functions  of  HP  2640  and  HP  2621-series  terminals 

SYNOPSIS 

hp  t-e]  [-m] 

DESCRIPTION 

hp  supports  special  functions  of  the  Hewlett-Packard  hp  2640  and  hp  2621  series  of  terminals,  with  the 
primary  purpose  of  producing  accurate  representations  of  most  nroff  output.  Atypical  use  is: 

nroff  -h  files  ...  |  hp 

Regardless  of  the  hardware  options  on  a  given  terminal,  hp  tries  to  do  sensible  things  with  underlining 
and  reverse  line-feeds.  If  the  terminal  has  the  "display  enhancements"  feature,  subscripts  and  superscripts 
can  be  indicated  in  distinct  ways.  If  it  has  the  "mathematical -symbol"  feature,  Greek  and  other  special 
characters  can  be  displayed. 

Options 

hp  recognizes  the  following  options: 

-e  Specify  that  your  terminal  has  the  "display  enhancements"  feature,  to  make  maximal  use  of 

the  added  display  modes.  Overstruck  characters  are  presented  in  the  Underline  mode. 
Superscripts  are  shown  in  Half-bright  mode,  and  subscripts  in  Half-bright,  Underlined 
mode.  If  this  flag  is  omitted,  hp  assumes  that  your  terminal  lacks  the  "display  enhance- 
ments" feature.  In  this  case,  all  overstruck  characters,  subscripts,  and  superscripts  are 
displayed  in  Inverse  Video  mode;  that  is,  dark-on-light,  rather  than  light-on-dark. 

-m  Request  minimization  of  output  by  removing  new-lines.  Any  contiguous  sequence  of  3  or 

more  new-lines  is  converted  into  a  sequence  of  only  2  new-lines;  that  is,  any  number  of  suc- 
cessive blank  lines  produces  only  a  single  blank  output  line.  This  allows  you  to  retain  more 
actual  text  on  the  screen. 

DIAGNOSTICS 

line  too  long 

The  representation  of  a  line  exceeds  1,024  characters. 

RETURN  VALUE 

hp  returns  zero  for  normal  termination,  and  2  for  all  errors. 

WARNINGS 

An  "overstriking  sequence"  is  defined  as  a  printing  character  followed  by  a  backspace  followed  by  another 
printing  character.  In  such  sequences,  if  either  printing  character  is  an  underscore,  the  other  printing 
character  is  shown  underlined  or  in  Inverse  Video;  otherwise,  only  the  first  printing  character  is  shown 
(again,  underlined  or  in  I  n  verse  Video).  Nothing  special  isdoneif  a  backspace  is  adjacent  to  an  ASCII  con- 
trol character.  Sequences  of  control  characters  (e.g.,  reverse  line-feeds,  backspaces)  can  make  text  "disap- 
pear"; in  particular,  tables  generated  by  tbl  that  contain  vertical  lines  will  often  be  missing  the  lines  of 
text  that  contain  the  "foot"  of  a  vertical  line,  unless  the  input  to  hp  is  piped  through  col  (see  col  (1)). 

Although  some  terminals  do  support  numerical  superscript  characters,  no  attempt  is  made  to  display  them. 

SEE  ALSO 

col(l),  neqn(l),  nroff (1),  tbl(l). 
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NAME 

hyphen  -  find  hyphenated  words 

SYNOPSIS 

hyphen  [files] 

DESCRIPTION 

hyphen  finds  all  the  hyphenated  words  ending  lines  in  files  and  prints  them  on  the  standard  output.  If  no 
arguments  are  given,  the  standard  input  is  used;  thus,  hyphen  can  be  used  as  a  filter. 

EXAMPLES 

Prepare  an  nroff  hyphenation  proofreading  file  for  textfile. 
mm  textfile    |  hyphen 

WARNINGS 

hyphen  cannot  cope  with  hyphenated  italics  (i.e.,  underlined)  words;  it  often  misses  them  completely  or 
mangles  them. 

hyphen  occasionally  gets  confused,  but  with  no  ill  effects  other  than  spurious  extra  output. 

SEE  ALSO 

mm(l),  nroff(l). 
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NAME 

iconv  -  code  set  conversion 

SYNOPSIS 

iconv  -f  fromcode  -t  tocode  [file  ...] 

DESCRIPTION 

iconv  converts  the  encoding  of  characters  in  the  input  files  from  the  fromcode  code  set  to  the  tocode  code 
set,  and  writes  the  results  on  standard  output.  If  no  input  files  are  given,  iconv  reads  from  standard 
input.  If  -  appears  as  an  input  file  name,  iconv  reads  standard  input  at  that  point.  -- can  be  used  to 
delimit  the  end  of  options  (see  getopt(3Q). 

Options 

iconv  recognizes  the  following  options: 


-f  fromcode    I  dentify  the  code  set  corresponding  to  option  argument  fromcode  as  the  code  set  that 
the  input  will  be  converted  "from". 


The  fromcode  and  tocode  names  can  beany  of  the  base  and  alias  names  listed  in  the  iconv  configuration  file, 
/usr/lib/nls/iconv/conf  ig .  iconv.  See  iconv(3C)  for  details  and  the  configuration  file  for  a  list 
of  supported  code  set  names. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  iconv  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. During  translation  of  the  file,  this  variable  is  superseded  by  the  use  of  the  fromcode  option-argument. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Singleand  multi-byte  character  code  sets  are  supported. 

WARNINGS 

If  an  input  character  does  not  have  a  valid  equivalent  in  the  code  set  selected  by  the  -t  option  (the  "to" 
code  set),  it  is  mapped  to  the  "galley  character",  if  it  has  been  defined  for  that  conversion,  (see  genxlt(l)  and 
iconv(3C) ). 

If  an  input  character  does  not  belong  to  the  code  set  selected  by  the  -f  option  (the  "from"  code  set),  the 
command  terminates. 

EXAMPLES 

Convert  the  contents  of  file  f  oo  from  code  set  Roman8  to  ISO  8859/1  and  store  the  results  in  file  bar. 


-t  tocode 


I  dentify  the  code  set  corresponding  to  option  argument  tocode  as  the  code  set  that  the 
input  will  be  converted  "to". 


iconv  -f  roman8  -t  iso8859_l   foo  >  bar 


FILES 


/usr/lib/nls/ iconv/ conf ig . iconv 


iconv  configuration  file 


AUTHOR 


iconv  was  developed  by  H  P. 
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SEE  ALSO 

getopt(3C),  iconv(3C). 

STANDARDS  CONFORMANCE 

iconv:  XPG2,  XPG3,  XPG4 
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NAME 

id  -  print  user  and  group  I  Ds  and  names 

SYNOPSIS 

id  [-u|-g|-G]  [-nr]  [-P]  [user] 

DESCRIPTION 

The  id  command  writes  a  message  to  standard  output,  giving  the  user  and  group  IDs  and  names  for  the 
process.  If  the  effective  and  real  I  Ds  are  different,  both  are  printed. 

If  the  process  has  supplementary  group  affiliations  (see  groups(l)),  the  supplementary  group  affiliations  are 
also  written. 

If  the  user  operand  is  specified,  and  the  effective  user  ID  of  the  process  is  superuser,  the  user  and  group 
I  Ds  of  the  selected  user  are  written.  I  n  this  case,  effective  I  Ds  are  assumed  to  be  identical  to  real  I  Ds. 

Options 

Thefollowing  options  modify  the  behavior  described  above. 

-g  Display  only  the  group  I D.  The  default  is  the  effective  group  ID;  to  modify,  use  the -r  option.  If 
the  process  has  supplementary  group  affiliations  that  are  different  from  the  effective  group  ID 
(or  the  real  ID  if  the  -r  option  is  used),  display  each  such  affiliation  on  the  same  line.  The 
default  is  decimal  format;  to  modify,  use  the -n  option. 

-G  Output  all  different  group  IDs  (effective,  real,  and  supplementary)  only,  using  the  format 
"%u\  n".  If  there  is  more  than  one  distinct  group  affiliation,  output  each  such  affiliation,  using  the 
format "  %u",  before  the  <newline>is  output. 

-n   With  A  -u,  -g,  or  -G,  display  the  I D  name  instead  of  the  I D  number. 

-r   With  -u,  -g,  or  -G,  display  the  real  I D  instead  of  the  effective  I D. 

-u  Display  only  the  user  I D.  The  default  is  the  effective  user  I D;  to  modify,  use  the  -r  option.  The 
default  is  decimal  format;  to  modify,  use  the -n  option. 

-P    Display  the  process  resource  group  I D.  See  HP  Process  Resource  Manager  in  DE  PEN  DEN  CI  ES. 

EXAMPLES 

To  display  the  current  user  and  group  data: 

id 

produces: 

uid=1834 (allanp)   gid=20 (users) 

To  display  the  group  I D  number  for  the  current  process: 

id  -g 
produces: 

20 

To  display  the  group  name  for  the  current  process: 

id  -gn 
produces: 

users 

To  display  the  user  and  group  data  for  another  user: 

id  ralford 
produces: 

uid=329 (ralford)   gid=20 (users) 

if  the  effective  user  I D  of  the  process  is  superuser.  Otherwise,  it  produces  the  data  for  the  invoking  pro- 
cess. 


HP-UX  Release  Hi:  December  2000 


-1- 


Section  1-349 


id(l) 


id(l) 


AUTHOR 

id  was  developed  by  H  P  and  AT&T. 

DEPENDENCIES 

HP  Process  Resource  Manager 

The  -P  option  requires  that  the  optional  HP  Process  Resource  Manager  (PRM)  software  be  installed  and 
configured.  See  prmconfig(l)  for  a  description  of  how  to  configure  HP  PRM,  and  prmconf(4)  for  the 
definition  of  the  process  resource  group. 

SEE  ALSO 

groups(l),  logname(l):  getuid(2). 

HP  Process  Resource  Manager:  prmconfig(l),  prmconf(4)  in  HP  Process  Resource  Manager  User'sGuide. 

STANDARDS  CONFORMANCE 

id:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

ident  -  identify  files  in  RCS 

SYNOPSIS 

ident  file  ... 

DESCRIPTION 

ident  searches  the  named  files  for  all  occurrences  of  the  pattern  $keyword  :  ...$,  where  keyword  is  one  of 


These  patterns  are  normally  inserted  automatically  by  the  RCS  co  command,  but  can  also  be  inserted 
manually  (see  co(l)). 

ident  works  on  text  files  as  well  as  object  files.  For  example,  if  the  C  program  in  file  f .  c  contains: 

char  rcsid[]    =  "$Header:     Header  information  $"; 
and  f  .c  iscompiled  intof  .o,  the  command: 

ident  f . c  f . o 


the  following: 


Author 
Date 


Log 

Revision 

Source 

State 


Header 
Locker 


prints: 


f  .c: 


$Header:    Header  information  $ 


f  .o: 


$Header:    Header  information  $ 


AUTHOR 


ident  was  developed  by  Walter  F.  Tichy. 


SEE  ALSO 

ci(l),  co(l),  rcs(l),  rcsdiff(l),  rcsintro(5),  rcsmerge(l),  rlog(l),  rcsfile(4). 
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NAME 

idlookup-  identify  the  user  of  a  particular  TCP  connection 
SYNOPSIS 

idlookup  host-or-ip-number  local -port  foreign-port 
DESCRIPTION 

idlookup  can  be  used  to  identify  the  user  at  the  remote  end  of  a  TCP  connection,  assuming  the  host  at 
the  other  end  is  running  an  Identification  Server. 

host-or-ip-number  is  the  name  of  the  host  at  the  other  end  of  the  connection,  or  its  I P  address. 

local-port  and  foreign-port  are  the  port  numbers,  or  service  names  of  the  ports  at  the  two  ends  of  the  con- 
nection. 

WARNING 

Note  that  the  references  to  local-port  and  foreign-port  follow  the  terminology  in  RFC931,  and  are  from  the 
point  of  view  of  the  server  rather  than  the  user. 

AUTHOR 

idlookup  was  originally  written  by  Peter  Eriksson.  The  manual  page  was  originally  written  by  Dave 
Sheild. 

SEE  ALSO 

sendmail(lM),  identd(llM),  RFC931. 
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NAME 

ied  -  input  editor  and  command  history  for  interactive  programs 
SYNOPSIS 

ied  [-dirt]  [-h  file]  [-s  size]  [-p  prompt]  [-k  charmap]  utility  [arguments  ...] 
DESCRIPTION 

ied  is  a  utility  command  that  is  intended  to  act  as  an  interface  between  the  user  and  an  interactive  pro- 
gram such  as  be,  bs,  or  Bourne  shell,  providing  most  of  the  line  editing  and  history  functionality  found  in 
the  Korn  shell,  ied  interprets  the  utility  name  as  the  command  to  be  executed,  and  passes  arguments  as 
the  arguments  to  the  utility.  Subsequent  input  to  utility  then  has  access  to  editing  and  history  functions 
very  similar  to  those  provided  by  ksh. 

ied  monitors  the  state  of  the  pty  it  uses  to  run  the  command,  and,  whenever  the  application  it  is  running, 
changes  the  state  from  the  state  of  the  tty  when  ied  started,  ied  becomes  "transparent".  This  allows 
programs  to  do  shell  escapes  to  screen-smart  programs.  In  general,  ied  should  not  in  any  way  interfere 
with  any  action  taken  by  any  program  for  which  it  provides  a  front  end.  This  includes  Korn  shell  itself:  in 
this  case  ied  would  provide  history  for  any  application  that  was  run  by  ksh,  and  ksh  would  provide  its 
own  independent  history.  In  a  useful  extreme  case,  ied  can  be  used  as  a  front  end  to  the  login  shell 
(which  might  be  ksh  or  csh).  In  this  case,  all  applications  that  use  normal  line  editing  gain  line  editing 
and  history,  sharing  a  single  history.  The  shell  would  continue  to  have  its  own  independent  history  if  it 
provides  such  a  mechanism. 

When  ied  is  in  its  transparent  mode,  no  history  is  saved.  In  particular  the  ex  mode  of  vi  does  not  use 
normal  line  editing  (rather,  it  simulates  it)  and  ied  cannot  provide  history  in  this  case.  The  Subject: 
and  address  line  editing  of  mailx  also  cannot  be  edited  with  ied. 

Options 

Several  options  and  command-linearguments  control  ied's  operation: 

-d  Debug  mode.  Print  information  about  the  operation  of  the  program.  It  is  best  used  to 

determine  if  a  program  puts  ied  into  transparent  mode  unexpectedly. 

-h  filename  Keep  the  history  in  a  file  named  filename.  If  a  file  of  that  namealready  exists  and  is  a 
history  file,  the  latter  part  of  it  (the  last  size  lines  as  specified  by  the  -s  option)  is 
used  as  the  initial  value  of  the  history.  If  the  -h  option  is  not  used,  the  environment 
variable  iedhistfile  is  used  to  supply  the  name.  If  neither  are  present  an 
unnamed  temporary  file  is  used,  and  no  initial  value  is  provided. 

-i  Force  interactive  mode.  Normally  ied  simply  execs  the  command  to  which  it  is 

asked  to  be  a  front  end  when  the  standard  input  is  not  a  tty  (this  allows  aliases  to  be 
used  for  commands  used  in  shells  without  interfering  with  their  operation).  This 
option  forces  ied  to  remain  as  a  front  end,  and  all  editing  functions  are  in  place. 
This  permits  a  utility  that  behaves  differently  in  interactive  and  batch  modes  to  be 
driven  from  a  pipe  or  file  in  interactive  mode.  This  is  particularly  useful  in  testing 
commands  that  make  this  distinction. 

-k  charmap  charmap  is  a  file  of  256  or  fewer  lines.  The  line  number  in  the  file  is  the  ordinal  of  a 
character  as  seen  as  input  by  ied,  and  the  character  on  the  line  is  the  character  gen- 
erated as  output  (and  also  used  as  editing  characters).  This  allows  remapping  of  (ordi- 
nary) keys  such  as  for  a  Dvorak  keyboard.  Characters  must  start  in  column  one  of 
each  line,  and  be  represented  as  1-4  characters  followed  by  a  space  or  the  new-line 
character  for  the  next  line.  Characters  after  the  space  are  ignored  as  comments. 
Single-character  entries  represent  themselves.  Two-character  entries  where  the  first 
character  is  a  circumflex  (")  converts  the  second  character  to  the  corresponding  con- 
trol character.  Two-character  sequences  where  the  first  character  is  backslash  (\)  use 
theC  language  conventions: 

\n    newline       \s  space 

\\     escape        \0  null 

\r    return         \f  formfeed 
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\t    tab  \v    vertical  tab 

\b  backspace 

Three-  and  four-character  sequences  must  be  \nn  or  \nnn,  giving  the  octal  value  for 
the  character.  If  charmap  is  less  than  256  lines  long,  the  remaining  characters  are 
mapped  to  themselves. 

-p  prompt  Many  commands  do  not  prompt  when  ready  for  input,  ied  approximates  a  prompt- 
ing mechanism  for  such  commands.  This  is  not  always  perfectly  successful,  but  for 
many  commands  it  helps.  In  the  worst  case,  the  prompt  is  interspersed  with  output 
in  the  wrong  location,  prompt  is  a  string  as  used  in  the  format  argument  to 
printf(3S).  Theonly  %  conversions  that  can  be  included  are  up  to  one  instance  of  %d 
which  is  converted  to  the  sequential  number  of  the  command,  and  any  number  of 
occurrences  of  %%  which  is  treated  as  a  literal  %  character.  Prompting  is  suppressed 
when  ied  is  operating  in  transparent  mode. 

-r  This  sets  "non-raw"  mode.  Normally  ied  uses  its  own  editing  capabilities  when  read- 

ing simple  text.  This  causes  ied  to  use  tty  line  discipline  most  of  the  time.  The 
disadvantage  of  the  default  mode  is  that  more  context  switches  and  general  processing 
are  required.  The  advantage  is  that  ied  is  more  transparent.  For  example,  to 
specifically  send  an  end-of-file  in  the  non-raw  mode  requires  that  the  end-of-file  char- 
acter (usually  Ctrl-D)  be  followed  by  a  carriage  return.  Similarly  the  "literal  next" 
function  (Ctrl-V)  cannot  escape  the  line-eraseand  line-kill  functions  in  non-raw  mode. 

-s  size  This  option  specifies  the  size  of  the  history  buffer.  When  ied  is  started  with  an 

existing  history  file,  approximately  the  last  size  lines  are  available  to  the  history 
mechanism  (the  number  is  not  guaranteed  to  be  exactly  size).  Other  lines  in  the  file 
are  retained  until  such  time  as  ied  is  started  on  that  history  file  and  it  exceeds 
approximately  4K  bytes  in  size,  at  which  time  ied  discards  older  entries  at  the 
beginning  of  the  file  until  it  is  near  4  Kbytes  in  size.  Since  this  occurs  only  at  startup, 
history  files  can  grow  to  be  quite  large  between  restarts.  Larger  values  of  size  make 
the  process  image  larger. 

If  -s  is  not  specified,  the  value  of  the  environment  variable  IEDHISTSIZE  isused. 
If  neither  is  specified,  a  default  is  used. 

-t  Set  transparent  mode.  This  forces  ied  to  permanently  be  in  transparent  mode  (as 

discussed  above).  It  is  primarily  useful  with  -i  for  some  classes  of  automated  pro- 
cessing. In  particular,  it  is  useful  for  driving  a  command  if  the  command  takes  as 
input  what  ied  would  interpret  as  editing  characters.  Thus  with  the  appropriate 
combinations  of  -i  and  -t,  it  is  possible  to  drive  an  editor  such  as  vi  or  a  screen- 
smart  application  from  a  batch  file. 

Should  something  go  wrong  with  ied,  the  SIGQUIT  signal,  repeated  3  times,  usually  aborts  ied.  The 
exception  is  the  case  of  a  fully  transparent  application,  where  ied  must  be  killed  from  another  window  or 
terminal.  This  is  really  relevant  only  when  there  is  no  way  to  direct  the  serviced  process  to  terminate 
itself. 

The  editing  capabilities  of  ied  are  essentially  those  found  in  ksh.  Only  those  that  differ  from  ksh  are 
described  below.  As  in  ksh,  the  style  of  editing  is  determined  from  the  environment  variable  VISUAL,  or 
from  EDITOR  if  VISUAL  is  not  specified.  The  value  examined  should  end  in  vi,  emacs,  or  gmacs  to 
specify  an  editor  type.  If  it  does  not,  ied  does  no  editing,  and  history  is  not  accessible. 

I  n  vi  mode: 

J  J  oin  lines.  Considering  the  most  recently  edited  line  (which  is  empty  immedi- 

ately after  a  line  is  sent  to  the  application)  to  be  the  "last  line"  of  the  history,  the 
current  line  being  displayed  from  the  history  is  appended  to  the  end  of  the  last 
line,  and  the  position  in  the  history  is  reset  to  be  at  the  last  line  which  is  then 
displayed.  A  space  is  inserted  between  the  old  and  new  text  on  the  last  line. 
The  cursor  is  left  on  that  space.  Because  ied's  understanding  of  line  continua- 
tion is  minimal,  this  is  useful  for  editing  long  statements. 

v  Not  supported. 

V  Not  supported. 

#  Sends  nothing  to  the  application,  but  inserts  the  line  in  the  history  (useful  for 

adding  comments  to  history  file). 
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<esc>,  *,=  (Filenameexpansion).  Not  supported. 

@  Macro  expansion.  Not  supported. 

Note  however  that  ksh  has  a  rarely-used  function  _  that  substitutes  words 
from  the  previous  line  (this  is  not  the  macro  $_,  but  rather  an  editor  command). 
If  a  preceding  count  is  given,  it  uses  the  countth  word  of  the  last  line.  This  is 
much  more  useful  with  ied. 

I  n  emacs/gmacs  mode: 

M-*:  M-=,  M-oso 

(filenameexpansion)  Not  supported. 

Note  that  the  command  M-.  (and  it's  synonym  M-_)  provide  the  same  func- 
tionality as  the  vi  mode  _  command. 

Macro  expansion.     Not  supported. 

A0  Although  supported,  it  may  not  always  appear  correctly  on  the  screen.  The  "L 

command  can  be  used  to  redraw  the  line.  See  below  for  the  discussion  on 
prompting. 

EXAMPLES 

Add  interactive  editing  to  the  be  command: 

ied  be 

Execute  vi  on  testfile  using  comands  taken  from  script : 

cat  script    |    ied  -i  -t  vi  testfile 

Note  that  without  the  use  of  ied,  vi  would  misbehave  because  its  standard  input  would  not  be  a  terminal 
device.  I  n  this  case  the  -t  is  not  required  because  vi  puts  itself  in  raw  mode,  but  for  an  application  that 
does  not,  -t  might  be  required. 

The  command  line 

ied  -i  -t  grep  '~x:'   data_file    |  tee  x_lines 

searches  the  file  data_file  for  lines  beginning  with  x: ,  sending  one  copy  to  the  terminal  and  a  second 
tofilex_lines,  just  I  ike  the  command  line 

grep  '~x:'   data_file    |  tee  x_lines 

The  difference  is  that  in  the  command  line  without  ied,  grep  writes  directly  to  a  pipe,  and  thus  buffers 
its  output.  If  data_f  ile  is  very  large  and  not  many  lines  match  the  pattern,  output  to  the  terminal  is 
delayed.  By  using  ied,  the  output  of  grep  goes  to  a  pty  instead,  which  causes  grep  to  output  each  line 
as  it  is  ready. 

WARNINGS 

Since  ied  cannot  know  everything  about  every  application,  it  is  possiblethat  it  can  become  confused,  with 
either  the  timing  or  the  prompt  being  out  of  phase  with  the  application.  Since  the  use  of  ied  is  never 
required,  it  is  the  user's  choice  to  determine  whether  the  application  is  more  usable  with  or  without  ied. 
Ingeneral,  however,  programs  that  do  not  confuse  ied  are  usually  also  the  most  likely  to  benefit  from  its 
use. 

ied  tries  to  intuit  the  currently  active  prompt  when  it  is  not  providing  one  itself.  However,  this  is  not 
always  successful.  Even  when  it  is  successful,  the  timing  of  ied  and  the  serviced  command  may  occasion- 
ally confuse  the  output.  The  ~L  commands  in  both  emacs  and  vi  modes  redraw  the  edit  line  in  a  consistent 
fashion  that  can  be  used  to  create  the  next  command. 

AUTHOR 

ied  was  developed  by  H  P. 

SEE  ALSO 

ksh(l). 
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NAME 

insertmsg-  usefindstr(l)  output  to  insert  calls  to  catgets(3C) 
SYNOPSIS 

insertmsg  [-h]  [-nnumber]  [-iamount]  [-snumber]  stringlist 
DESCRIPTION 

insertmsg  examines  the  file  stringlist,  which  is  assumed  to  be  the  output  of  findstr  after  subsequent 
editing  to  remove  any  strings  that  do  not  need  to  be  localized  (see  findstr(l)).  If  the  -h  option  is  specified, 
insertmsg  places  the  foil  owing  lines  at  the  beginning  of  each  file  named  in  stringlist: 

#ifndef  NLS 

fdefine  catgets (i, sn,mn, s)  (s) 
#else  NLS 

jfdefine  NL_SETN  number 
#include  <nl_types . h> 
#endif  NLS 

where  number  is  a  set  number  defined  by  the  -s  option;  the  default  is  1.  For  each  string  in  stringlist, 
insertmsg  surrounds  the  string  in  the  corresponding  file  with  an  expression  of  the  form: 

(catgets  (catd, NL_SETN,  msgnum,  "default  string") ) 

The  default  string  is  the  original  string  referenced  by  the  line  in  stringlist,  and  msg  num  is  replaced  by  the 
message  number  assigned  to  that  string.  The  assigned  message  numbers  begin  with  the  number  defined  by 
the  -n  option  and  are  incremented  by  the  amount  defined  by  the  -i  option.  The  default  is  1  for  both  the 
starting  message  number  and  the  increment.  If  name,  c  is  the  file  to  be  modified,  as  specified  within  the 
stringlist  file,  insertmsg  places  the  modified  source  in  nl_name.  c.  The  user  must  then  manually  edit  the 
filenl_name.c  to  insert  the  foil  owing  statements: 

nl_catd  catd; 

catd  =  catopen  ("  appropriate  message  catalog" ,  0)  ; 

The  data  type  nl_catd  isdefined  in  <nl_types.h>and  catd  isa  parameter  to  the  calls  to  catgets, 
which  are  inserted  for  each  string  from  stringlist. 

insertmsg  also  sends  to  the  standard  output  a  file  that  can  be  used  as  input  to  gencat  (see  gencat(l)). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single- and/or  multi-byte  characters. 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_CTYPE  or  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  insertmsg  behaves  as  if  all  internationalization  variables  are  set  to 
"C".  See  environ (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

If  insertmsg  does  not  find  opening  or  closing  double  quotes  where  required  in  the  strings  file,  it  prints 
insertmsg  exiting  :  lost  in  strings  file  and  aborts.  If  this  happens,  check  the  strings 
file  to  ensure  that  the  lines  that  have  been  kept  there  have  not  been  altered. 

WARNINGS 

If  the  -h  option  is  not  used,  it  may  be  necessary  to  manually  add  the  following  statement  to  the  file 
created  by  insertmsg: 

#include  <nl_types . h> 

insertmsg  inserts  a  pointer  to  a  static  area  that  is  overwritten  on  each  call. 

The  insertmsg  command  is  HP  proprietary,  not  portableto  other  vendors'  systems,  and  will  not  be  pro- 
vided in  future  HP-UX  releases. 
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AUTHOR 

insertmsg  was  developed  by  HP. 

SEE  ALSO 

findstr(l),  gencat(l),  catgets(3C),  catopen(3C). 
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NAME 

icstat  -  report  I/O  statistics 

SYNOPSIS 

iostat  [-t]  [interval  [count]] 

DESCRIPTION 

iostat  iteratively  reports  I/O  statistics  for  each  active  disk  on  the  system.  Disk  data  is  arranged  in  a 
four-column  format: 

Column  Heading  Interpretation 


device  Device  name 

bps  K i I obytes  transferred  per  second 

sps  N umber  of  seeks  per  second 

msps  Milli seconds  per  average  seek 


If  two  or  more  disks  are  present,  data  is  presented  on  successive  lines  for  each  disk. 

To  compute  this  information,  seeks,  data  transfer  completions,  and  the  number  of  words  transferred  are 
counted  for  each  disk.  Also,  the  state  of  each  disk  is  examined  HZ  times  per  second  (as  defined  in 
<sys/param.h>)  and  a  tally  is  made  if  the  disk  is  active.  These  numbers  can  be  combined  with  the 
transfer  rates  of  each  device  to  determine  average  seek  times  for  each  device. 

With  the  advent  of  new  disk  technologies,  such  as  data  striping,  where  a  single  data  transfer  is  spread 
across  several  disks,  the  number  of  milliseconds  per  average  seek  becomes  impossible  to  compute  accu- 
rately. At  best  it  is  only  an  approximation,  varying  greatly,  based  on  several  dynamic  system  conditions. 
For  this  reason  and  to  maintain  backward  compatibility,  the  milliseconds  per  average  seek  (  msps  )  field  is 
set  to  the  value  1.0. 

Options 

iostat  recognizes  the  following  options  and  command-line  arguments: 

-t  Report  termi  nal  statistics  as  well  as  disk  statistics.  Terminal  statistics  include: 

tin  Number  of  characters  read  from  terminals, 

tout  Number  of  characters  written  to  terminals. 

us  Percentage  of  time  system  (active  processors)  has  spent  in  user  mode, 

ni  Percentage  of  time  system  (active  processors)  has  spent  in  user  mode  run- 
ning low-priority  (nice)  processes, 

sy  Percentage  of  time  system  (active  processors)  has  spent  in  system  mode, 

id  Percentage  of  time  system  (active  processors)  has  spent  idling. 

interval  Display  successive  lines  which  are  summaries  of  the  last  interval  seconds.  The  first  line 
reported  is  for  the  time  since  a  reboot  and  each  subsequent  line  is  for  the  last  interval 
only. 

count         Repeat  the  statistics  count  times. 

EXAMPLES 

Show  current  I/O  statistics  for  all  disks: 

iostat 

Display  I/O  statistics  for  all  disks  every  10  seconds  until  interrupt  or  quit  is  pressed: 
iostat  10 

Display  I/O  statistics  for  all  disks  every  10  seconds  and  terminate  after  5  successive  readings: 
iostat  10  5 

Display  I/O  statistics  for  all  disks  every  10  seconds,  also  show  terminal  and  processor  statistics,  and  ter- 
minate after  5  successive  readings: 

iostat  -t  10  5 
WARNINGS 

Users  of  iostat  must  not  rely  on  the  exact  field  widths  and  spacing  of  its  output,  as  these  will  vary 
depending  on  the  system,  the  release  of  HP-UX,  and  the  data  to  be  displayed. 
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AUTHOR 

iostat  was  devel oped  by  the  University  of  California,  Berkeley,  and  HP. 
FILES 

/ usr/ include/ sys/param . h 

SEE  ALSO 

vmstat(l). 


HP-UX  Release  Hi:  December  2000 


-2- 


Section  1-359 


ipcrm(l) 


ipcrm(l) 


NAME 

ipcrm  -  remove  a  message  queue,  semaphore  set,  or  shared  memory  identifier 

SYNOPSIS 

ipcrm  [option]... 

DESCRIPTION 

The  ipcrm  command  removes  one  or  more  specified  message  queue,  semaphore  set,  or  shared  memory 
identifiers. 

Options 

The  identifiers  are  specified  by  the  foil  owing  options: 

-m  shmid       Remove  the  shared  memory  identifier  shmid  from  the  system.  The  shared  memory 
segment  and  data  structure  associated  with  it  are  destroyed  after  the  last  detach. 

-q  msqid        Remove  the  message  queue  identifier  msqid  from  the  system  and  destroy  the  message 
queue  and  data  structure  associated  with  it. 

-s  semid        Remove  the  semaphore  identifier  semid  from  the  system  and  destroy  the  set  of  sema- 
phores and  data  structure  associated  with  it. 

-M  shmkey      Remove  the  shared  memory  identifier,  created  with  key  shmkey,  from  the  system. 

The  shared  memory  segment  and  data  structure  associated  with  it  are  destroyed  after 
the  last  detach. 

-Q  msgkey      Remove  the  message  queue  identifier,  created  with  key  msgkey,  from  the  system  and 
destroy  the  message  queue  and  data  structure  associated  with  it. 

-S  semkey      Remove  the  semaphore  identifier,  created  with  key  semkey,  from  the  system  and  des- 
troy the  set  of  semaphores  and  data  structure  associated  with  it. 

The  details  of  the  removals  are  described  in  msgctl  (2),  shmctl  (2),  and  semctl  (2).  The  identifiers  and  keys 
can  be  found  by  using  ipcs  (see  ipcs(l)). 

SEE  ALSO 

ipcs(l),  msgctl(2),  msgget(2),  msgop(2),  semctl(2),  semget(2),  semop(2),  shmctl(2),  shmget(2),  shmop(2). 

STANDARDS  CONFORMANCE 

ipcrm:  SVID2,  SVID3 
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NAME 

ipcs  -  report  status  of  i nterprocess  communication  facilities 
SYNOPSIS 

ipcs  [-mqs]  [-abcopt]  [-C  core]  [-N  namelist] 
DESCRIPTION 

ipcs  displays  certain  information  about  active  interprocess  communication  facilities.  With  no  options,  ipcs 
displays  information  in  short  format  for  the  message  queues,  shared  memory  segments,  and  semaphores 
that  are  currently  active  in  the  system. 

Options 

The  foil  owing  options  restrict  the  display  to  the  corresponding  facilities, 
(none)  This  is  equivalent  to -mqs. 

-m  Display  information  about  active  shared  memory  segments. 

-q  Display  information  about  active  message  queues. 

-s  Display  information  about  active  semaphores. 

Thefollowing  options  add  columns  of  data  to  the  display.  See  "Column  Description"  below. 

(none)  Display  default  columns:  for  all  facilities:  T,  ID,  KEY,  MODE,  OWNER,  GROUP. 

-a  Display  all  columns,  as  appropriate.  This  is  equivalent  to  -bcopt. 

-b  Display  largest-allowable-size  information:  for  message  queues:  QBYTES;  for  shared 

memory  segments:  SEGSZ;  for  semaphores:  NSEMS. 

-c  Display  creator's  login  nameand  group  name:  for  all  facilities:  CREATOR,  CGROUP. 

-o  Display  information  on  outstanding  usage:  for  message  queues:  CBYTES,  QNUM;  for 

shared  memory  segments:  NATTCH. 

-p  Display  process  number  information:  for  message  queues:   LSPID,  LRPID;  for 

shared  memory  segments:  CPID,  LPID. 

-t  Display  time  information:  for  all  facilities:  CTIME;  for  message  queues:  STIME, 

RTIME;  for  shared  memory  segments:  ATIME,  DTIME;  for  semaphores:  OTIME. 

Thefollowing  options  redefine  the  sources  of  information. 

-C  core  Use  core  in  place  of  /dev/kmem.  core  can  be  a  core  file  or  a  directory  created  by 

savecrash  or  savecore . 

— N  namelist    Use  file  namelist  or  the  namelist  within  core  in  place  of /stand/vmunix.  It  opens 
a  crash  dump  for  reading.  Please  refer  to  cr_open(3)  for  more  details. 

Column  Descriptions 

The  column  headings  and  the  meaning  of  the  columns  in  an  ipcs  listing  are  given  below.  The  columns  are 
printed  from  left  to  right  in  the  order  shown  below. 

T  Facility  type: 

m     Shared  memory  segment 
q     Message  queue 
s  Semaphore 

ID  The  identifier  for  the  facility  entry. 

KEY  The  key  used  as  an  argument  to  msgget  ()  ,  semget  ()  ,  or  shmget  ()  to  create 

the  facility  entry.  (Note:  The  key  of  a  shared  memory  segment  is  changed  to 
IPC_PRIVATE  when  the  segment  has  been  removed  until  all  processes  attached  to 
the  segment  detach  it.) 

MODE  Thefacility  access  modes  and  flags:  The  mode  consists  of  11  characters  that  are  inter- 

preted as  follows: 

The  first  two  characters  can  be: 
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R  A  process  is  waiting  on  a  msgrcv()  . 
S     A  process  is  waiting  on  a  msgsnd()  . 

D  The  associated  shared  memory  segment  has  been  removed.  It  will  disap- 
pear when  the  last  process  attached  to  the  segment  detaches  it. 

C  The  associated  shared  memory  segment  is  to  be  cleared  when  the  first 
attach  is  executed. 

The  corresponding  special  flag  is  not  set. 

The  next  9  characters  are  interpreted  as  three  sets  of  three  characters  each.  The  first 
set  refers  to  the  owner's  permissions,  the  next  to  permissions  of  others  in  the  group  of 
the  facility  entry,  and  the  last  to  all  others. 

Within  each  set,  the  first  character  indicates  permission  to  read,  the  second  character 
indicates  permission  to  write  or  alter  the  facility  entry,  and  the  last  character  is 
currently  unused. 

r  Read  permission  is  granted, 
w  Write  permission  is  granted, 
a     Alter  permission  is  granted. 

The  indicated  permission  is  not  granted. 

OWNER  Thelogin  name  of  the  owner  of  the  facility  entry. 

GROUP  Thegroup  name  of  the  group  of  the  owner  of  the  facility  entry. 

CREATOR  Thelogin  name  of  the  creator  of  the  facility  entry. 

CGROUP  Thegroup  name  of  thegroup  of  the  creator  of  the  facility  entry. 

CBYTES         The  number  of  bytes  in  messages  currently  outstanding  on  the  associated  message 
queue. 

QNUM  The  number  of  messages  currently  outstanding  on  the  associated  message  queue. 

QBYTES         The  maximum  number  of  bytes  allowed  in  messages  outstanding  on  the  associated 
message  queue. 

LSPID  The  process  ID  of  the  last  process  to  send  a  message  to  the  associated  message  queue. 

LRPID  The  process  I D  of  the  last  process  to  receive  a  message  from  the  associated  message 

queue. 

STIME  The  time  the  last  msgsnd  ( )  message  was  sent  to  the  associated  message  queue. 

RTIME  The  time  the  last  msgrcv()  message  was  received  from  the  associated  message 
queue. 

CTIME  Thetime  when  the  associated  facility  entry  was  created  or  changed. 

NATTCH  The  number  of  processes  attached  to  the  associated  shared  memory  segment. 

SEGSZ  The  size  of  the  associated  shared  memory  segment. 

CPID  The  process  I D  of  the  creating  process  of  the  shared  memory  segment. 

LPID  The  process  I D  of  the  last  process  to  attach  or  detach  the  shared  memory  segment. 

at  I  me  The  time  the  last  shmat  ()  attach  was  completed  to  the  associated  shared  memory 

segment. 

DTIME  The  time  the  last  shmdt  ( )  detach  was  completed  on  the  associated  shared  memory 

segment. 

NSEMS  The  number  of  semaphores  in  the  set  associated  with  the  semaphore  entry. 

OTIME  The  time  the  last  semopO  semaphore  operation  was  completed  on  the  set  associated 

with  the  semaphore  entry. 

WARNINGS 

ipcs  produces  only  an  approximate  indication  of  actual  system  status  because  system  processes  are  con- 
tinually changing  while  ipcs  is  acquiring  the  requested  information. 

Do  not  rely  on  the  exact  field  widths  and  spacing  of  the  output,  as  these  will  vary  depending  on  the  system, 
the  release  of  HP-UX,  and  the  data  to  be  displayed. 
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FILES 

/dev/kmem  Kernel  virtual  memory 

/etc/group  Group  names 

/etc/passwd  User  names 

/stand/vmunix  System  namelist 

SEE  ALSO 

msgop(2),  semop(2),  shmop(2). 

STANDARDS  CONFORMANCE 

ipcs:  SVID2,  SVID3 
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NAME 

join  -  relational  database  operator 

SYNOPSIS 

join  [options]  filel  file2 


DESCRIPTION 

join  forms,  on  the  standard  output,  a  join  of  the  two  relations  specified  by  the  lines  of  filel  and  file2.  If 
filel  or  file2  is  -,  the  standard  input  is  used. 

filel  and  file2  must  be  sorted  in  increasing  collating  sequence  (see  Environment  Variables  below)  on  the 
fields  on  which  they  are  to  be  joined;  normally  the  first  in  each  line. 

The  output  contains  one  line  for  each  pair  of  lines  in  filel  and  file2  that  have  identical  join  fields.  The  out- 
put line  normally  consists  of  the  common  field  followed  by  the  rest  of  the  line  from  filel,  then  the  rest  of  the 
line  from  file2. 

Thedefault  input  field  separators  are  space,  tab,  or  new-line.  In  thiscase,  multiple  separators  count  as  one 
field  separator,  and  leading  separators  are  ignored.  Thedefault  output  field  separator  is  a  space. 

Some  of  the  below  options  use  the  argument  n.  This  argument  should  be  a  1  or  a  2  referring  to  either 
filel  or  file2,  respectively. 

Options 

-a  n  I  n  addition  to  the  normal  output,  produce  a  line  for  each  unpairableline  in  file  n,  where  n  is  1 
or  2. 

-e  s  Replace  empty  output  fields  by  string  s. 

-j  m  J  oin  on  field  m  of  both  files.  The  argument  m  must  be  delimited  by  space  characters.  This 
option  and  the  following  two  are  provided  for  backward  compatibility.  Useofthe  -land  -2 
options  (  see  below  )  is  recommended  for  portability. 

-jl  m      J  oin  on  field  m  of  filel. 

-j2  m      J  oin  on  field  m  of  file2. 

-o  list  Each  output  line  comprises  the  fields  specified  in  list,  each  element  of  which  has  the  form 
n  .m,  where  n  is  a  file  number  and  m  is  a  field  number.  The  common  field  is  not  printed 
unless  specifically  requested. 

-t  c  Use  character  c  as  a  separator  (tab  character).  Every  appearance  of  c  in  a  line  is  significant. 

The  character  c  is  used  as  the  field  separator  for  both  input  and  output. 

-v  filenumber 

Instead  of  the  default  output,  produce  a  line  only  for  each  unpairable  line  in  file  number, 
where  file  number  is  1  or  2. 

-1  f  J  oin  on  field  f  of  file  1.  Fields  are  numbered  starting  with  1. 

-2  f  J  oi n  on  field  f  of  file  2.  Fields  are  numbered  starting  with  1. 


EXTERNAL  INFLUENCES 
Environment  Variables 

LC_COLLATE  determines  the  collating  sequence  join  expects  from  input  files. 

LC_CTYPE  determines  the  alternative  blank  character  as  an  input  field  separator,  and  the  interpretation 
of  data  within  files  as  single  and/or  multi-byte  characters.  LC_CTYPE  also  determines  whether  the 
separator  defined  through  the  -t  option  isa  single-  or  multi -byte character. 

If  LC_COLLATE  or  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is 
set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization 
variable  contains  an  invalid  setting,  join  behaves  as  if  all  internationalization  variables  are  set  to  "C" 
(see  envi  ron(5)). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported  with  the  exception  that  multi-byte-character  file 
names  are  not  supported. 
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EXAMPLES 

The  following  command  line  joins  the  password  file  and  the  group  file,  matching  on  the  numeric  group  id, 
and  outputting  the  login  name,  the  group  name,  and  the  login  directory.  It  is  assumed  that  the  files  have 
been  sorted  in  the  collating  sequence  defined  by  the  LC_COLLATE  or  LANG  environment  variable  on  the 
group  id  fields. 

join  -1  4  -2  3  -o  1.1  2.1  1.6  -t :    /etc/passwd  /etc/group 

Thefollowing  command  produces  an  output  consisting  all  possible  combinations  of  lines  that  have  identical 
first  fields  in  the  two  sorted  files  sfl  and  sf2,  with  each  line  consisting  of  the  first  and  third  fields  from 
sorted_f  ilel  and  the  second  and  fourth  fields  from  sorted_f  ile2  : 

join  -jl  1  -j2  1  -o  1.1,2.2,1.3,2.4  sorted_f ilel  sorted_file2 
WARNINGS 

With  default  field  separation,  the  collating  sequence  is  that  of  sort  -b;  with  -t,  the  sequence  is  that  of  a 
plain  sort. 

The  conventions  of  join,  sort,  comm,  uniq,  and  awk  are  incongruous. 

Numeric  filenames  may  cause  conflict  when  the  -o  option  is  used  immediately  before  listing  filenames. 

AUTHOR 

join  was  developed  byOSF  and  HP. 

SEE  ALSO 

awk(l),  comm(l),  sort(l),  uniq(l). 

STANDARDS  CONFORMANCE 

join:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 


HP-UX  Release  Hi:  December  2000 


-2- 


Section  1-365 


kdestroy(l) 


kdestroy(l) 


NAME 

kdestroy  -  destroy  Kerberos  tickets 

SYNOPSIS 

kdestroy  [-q]  [-c  cachefilename] 

DESCRIPTION 

The  kdestroy  utility  destroys  the  user's  active  Kerberos  authorization  tickets  by  writing  zeros  to  the 
specified  credentials  cache  that  contains  them.  If  the  credentials  cache  is  not  specified,  the  default  creden- 
tials cache  is  destroyed. 

Options 

-q  Run  quietly.  Normally  kdestroy  beeps  if  it  fails  to  destroy  the  user's  tickets.  The 

-q  flag  suppresses  this  behavior. 

-c  cachefilename  Use  cachefilename  as  the  credentials  ticket  cache  name  and  location.  If  thisoption  is 
not  used,  the  default  cache  name  and  location  is  used. 

The  default  credentials  cache  may  vary  between  systems.  I  f  the  KRB5CCNAME  environment  variable  is  set, 
its  value  is  used  to  name  the  default  ticket  cache. 

Most  installations  recommend  that  you  place  the  kdestroy  command  in  your  .  logout  file,  so  that  your 
tickets  are  destroyed  automatically  when  you  log  out. 

Note 

For  DCE  operations  use  /opt/dce/bin/kdestroy. 

Environment 

kdestroy  uses  the  foil  owing  environment  variable: 

KRB5CCNAME         Location  of  the  credentials  ticket  cache. 
WARNINGS 

Only  the  tickets  in  the  specified  credentials  cache  are  destroyed.  Separate  ticket  caches  are  used  to  hold 
root  instance  and  password  changing  tickets.  Even  these  should  be  destroyed.  It  is  recommended  that  to 
keep  all  user  tickets  in  a  single  credentials  cache. 

FILES 

/tmp/krb5cc_{uid}     Default  credentials  cache.  {uid}is  the  decimal  U I D  of  the  user. 
AUTHOR 

kdestroy  was  developed  by  the  Massachusetts  I  nstitute  of  Technology. 

SEE  ALSO 

kerberos(9),  kinit(l),  klist(l). 
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NAME 

kermit  -  C-Kermit  7.0  communications  software  for  serial  and  network  connections:  modem  dialing,  file 
transfer  and  management,  terminal  connection,  character-set  translation,  numeric  and  alpha  paging,  and 
script  programming 

SYNOPSIS 

kermit  [command-file]  [options...] 

DESCRIPTION 

Kermit  is  a  family  of  file  transfer,  management,  and  communication  software  programs  from  the  Kermit 
Project  at  Columbia  University  availablefor  most  computers  and  operating  systems.  The  version  of  Kermit 
for  Hewlett-Packard  HP-UX,  called  C-Kermit,  supports  both  serial  connections  (direct  or  dialed)  and 
TCP/I  P  connections. 

C-Kermit  can  bethought  of  as  a  user-friendly  and  powerful  alternative  to  cu,  tip,  uucp,  ftp,  telnet, 
rlogin,  expect,  and  even  your  shell;  a  single  package  for  both  network  and  serial  communications, 
offering  automation,  convenience,  and  language  features  not  found  in  the  other  packages,  and  having  a 
great  deal  in  common  with  its  cousins,  C-Kermit  on  other  UNIX  platforms,  Kermit  95  for  Windows  95,  Win- 
dows 98,  Windows  NT  and  2000,  and  OS/2;  MS-DOS  Kermit  for  PCs  with  DOS  and  Windows  3.x,  and  IBM 
Mainframe  Kermit- 370  for  VM/CMS,  MVS/TSO,  and  CICS.  C-Kermit  itself  also  runs  on  Digital  VMS,  Data 
General  AOS/VS,  Stratus  VOS,  OS-9,  QNX,  Plan  9,  the  Commodore  Amiga,  and  elsewhere.  Together,  C- 
Kermit,  Kermit  95,  MS-DOS  Kermit,  and  IBM  Mainframe  Kermit  offer  a  consistent  and  nearly  universal 
approach  to  inter-computer  communications. 

C-Kermit  7.0  is  Copyright  (C)  1985,  2000  by  the  Trustees  of  Columbia  University  in  the  City  of  New  York. 
For  use  and  redistribution  rights,  see  the  C-Kermit  COPYING.TXT  file  or  give  the  C-Kermit  COPYRIGHT 
command  (summary:  no  license  is  required  for  own  use;  no  license  is  required  for  distribution  with  Open 
Source  operating  systems;  a  license  is  required  for  certain  other  forms  of  redistribution). 

C-Kermit  7.0  is  included  with  HP-UX  by  Hewlett-Packard  in  partnership  with  the  Kermit  Project  at  Colum- 
bia University. 

C-Kermit  6.0  is  thoroughly  documented  in  the  book  Using  C-Kermit  by  Frank  da  Cruz  and  Christine  M. 
Gianone,  Digital  Press,  Second  Edition,  1997;  see  REFERENCES  at  the  end  of  this  manual  page.  This 
manual  page  is  not  a  substitute  for  the  book.  If  you  are  a  serious  user  of  C-Kermit,  particularly  if  you  plan 
to  write  C-Kermit  script  programs,  you  should  purchase  the  manual.  Book  sales  are  the  primary  source  of 
funding  for  the  nonprofit  Kermit  Project. 

Any  new  features  added  since  the  most  recent  edition  of  the  book  was  published  are  documented  in  the 
online  file  ckermit2.upd  until  such  time  as  the  Third  Edition  of  the  book  is  ready.  Hints,  tips,  limitations, 
restrictions  are  listed  in  ckcker.txt  (general  C-Kermit)  and  ckuker.bwr  (UNIX-specific);  see  FILES  below. 
Please  consult  all  of  these  references  before  reporting  problems  or  asking  for  technical  support. 

Kermit  software  is  availablefor  hundreds  of  different  computers  and  operating  systems  from  Columbia 
University.  For  best  file-transfer  results,  please  use  C-Kermit  in  conjunction  with  real  Columbia  University 
Kermit  software  on  other  computers,  such  as  Kermit  95  for  Windows  95  and  NT  or  MS-DOS  Kermit  for 
DOS  3.x  or  Windows.  See  CONTACTS  below. 

MODES  OF  OPERATION 

C-Kermit  can  be  used  in  two  "modes":  remote  and  local.  I  n  remote  mode,  you  connect  to  the  HP-UX  sys- 
tem from  a  desktop  computer  and  transfer  files  between  your  desktop  computer  and  HP-UX  C-Kermit.  In 
that  case,  connection  establishment  (dialing,  TELNET  connection,  etc.)  is  handled  by  the  Kermit  program 
on  your  desktop  computer. 

In  local  mode,  C-Kermit  establishes  a  connection  to  another  computer  by  direct  serial  connection,  by  dial- 
ing a  modem,  or  by  making  a  network  connection.  When  used  in  local  mode,  C-Kermit  gives  you  a  terminal 
connection  to  the  remote  computer,  using  your  actual  terminal,  emulator,  or  UNIX  workstation  terminal 
window  or  console  driver  for  specific  terminal  emulation. 

C-Kermit  also  has  two  types  of  commands:  the  familiar  UNIX-style  command-line  options,  and  an  interac- 
tive dialog  with  a  prompt.  Command-line  options  give  you  access  to  a  small  but  useful  subset  of  C- 
Kermit's  features  for  terminal  connection  and  file  transfer,  plus  the  ability  to  pipe  files  into  or  out  of  Kermit 
for  transfer. 

Interactive  commands  give  you  access  to  dialing,  script  programming,  character-set  translation,  and,  in 
general,  detailed  control  and  display,  as  well  as  automation,  of  all  C-Kermit's  features.  Interactive  com- 
mands can  also  be  collected  into  command  files  or  macros.  C-Kermit's  command  and  script  language  is 
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portableto  many  and  diverse  platforms. 
STARTING  C-KERMIT 

You  can  start  C-Kermit  by  typing  /usr/bin/kermit,  or  just  kermit  if  your  PATH  includes 
/usr/bin,  possibly  followed  by  command-line  options.  If  there  are  no  "action  options"  on  the  command 
line  (explained  below),  C-Kermit  starts  in  interactive  command  mode;  you  will  see  a  greeting  message  and 
then  the  "C-Kermit>"  prompt.  If  you  do  include  action  options  on  the  command  line,  C-Kermit  takes  the 
indicated  actions  and  then  exits  directly  back  to  UNIX.  Either  way,  C-Kermit  executes  the  commands  in 
its  initialization  file,  /usr/share/lib/kermit/ckermit .  ini,  before  it  executes  any  other  com- 
mands, unless  you  have  included  the  '-Y'  (uppercase)  command-line  option,  which  means  to  skip  the  ini- 
tialization file,  or  you  have  included  the '-y    filename' option  to  specify  an  alternative  initialization  file. 

FILE  TRANSFER 

Here  is  the  most  common  scenariofor  Kermit  filetransfer.  Many  other  methods  are  possible,  most  of  them 
more  convenient,  but  this  basic  method  should  work  in  all  cases. 


•  Start  Kermit  on  your  local  computer  and  establish  a  connection  to  the  remote  computer.  If  C- 
Kermit  is  on  your  local  computer,  use  the  sequence  SET  MODEM  TYPE  modem-name,  SET  LINE 
device-name,  SET  SPEED  bits-per-second  ,  and  DIAL  phone-number  if  you  are  dialing;  SET  LINE 
and  SPEED  for  direct  connections;  SET  NETWORK  network-type  and  SET  HOST  host-name-or- 
addressfor  network  connections. 

•  SET  any  other  necessary  communication  parameters,  such  as  PARITY,  DUPLEX,  and  FLOW- 
CONTROL. 

•  GivetheCONNECT  command. 

•  Log  in  to  the  remote  computer. 

•  Start  Kermit  on  the  remote  computer,  give  it  any  desired  SET  commands  for  file-,  communication-, 
or  protocol -related  parameters.  If  you  will  be  transferring  binary  files,  give  the  command  SET 
FILE  TYPE  BINARY  totheKermit  program  that  will  be  sending  them. 

•  To  download  a  file  or  file  group,  give  the  remote  Kermit  a  SEND  command,  following  by  a 
filename  or  "wildcard"  file  specification,  for  example: 


To  upload  a  file  or  files,  give  the  remote  Kermit  a  RECEIVE  command.  The  sending  Kermit  will 
tell  the  receiving  Kermit  the  name  (and  other  attributes)  of  each  file. 

•  Escape  back  to  the  Kermit  program  on  your  local  (desktop)  computer.  If  your  local  computer  is 
running  C-Kermit,  type  Ctrl-\c  (Control-backslash  followed  by  the  letter  'c')  (on  NeXT  worksta- 
tions, useCtrl-]  c).  If  MS-DOS  or  Kermit  95,  useAlt-x  (hold  down  the  Alt  key,  press  'x').  Now  you 
should  see  your  local  Kermit  program's  prompt. 

•  If  you  will  be  transferring  binary  files,  give  the  command  SET  FILE  TYPE  BINARY  to  the  Kermit 
program  that  is  sending  the  files. 

•  If  you  are  downloading  files,  tell  the  local  Kermit  program  to  RECEIVE.  If  you  are  uploading, 
give  your  local  Kermit  program  a  SEND  command,  specifying  a  filename  or  wildcard  file 
specification.  In  other  words,  tell  the  remote  Kermit  program  what  to  do  first,  SEND  or 
RECEIVE,  then  escape  back  to  the  local  Kermit  and  give  it  the  opposite  command,  RECEIVE  or 
SEND. 

•  When  the  transfer  is  complete,  give  a  CONNECT  command.  Now  you  are  talking  to  Kermit  on  the 
remote  computer  again.  Type  EXIT  to  get  back  to  the  command  prompt  on  the  remote  computer. 
When  you  are  finished  using  the  remote  computer,  log  out  and  then  (if  necessary)  escape  back  to 
Kermit  on  your  local  computer.  Then  you  can  make  another  connection  or  EXIT  from  the  local 
Kermit  program. 

Note  that  other  methods  can  be  used  to  simplify  the  file-transfer  process:  client/server  operation,  in 
which  all  commands  are  given  to  the  client  and  passed  on  automatically  to  the  server,  and  autodownload 
(and  upload),  in  which  the  remote  Kermit  initiates  file  transfers  automatically  through  your  terminal  emu- 
lator. 

The  file  transfer  protocol  defaults  in  C-Kermit  7.0,  unlike  those  for  earlier  releases,  favor  speed  over 
robustness,  on  the  assumption  that  connections  in  these  times  are  usually  reliable  (over  TCP/IP  and/or 
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error-correcting  modems  with  hardware  flow  control).  If  you  experience  file  transfer  failures,  use  the  CAU- 
TIOUS or  ROBUST  commands  to  choose  more  conservative  (and  therefore  slower)  protocol  settings.  For 
fine  tuning  of  performance,  you  can  choose  specific  packet  lengths,  window  sizes,  and  control -character 
prefixing  strategies  as  explained  in  Chapter  12  of  the  manual,  Using  C-Kermit. 

If  you  are  accessing  a  remote  host  where  C-Kermit  resides  via  Telnet  or  other  connection  that  is 
guaranteed  reliable  from  end  to  end,  and  both  Kermits  support  it  (C-Kermit  7.0  does),  a  new  "streaming" 
form  of  the  Kermit  protocol  is  used  automatically  to  give  ftp-like  speeds  (the  limiting  factor  being  the  over- 
head from  the  remote  Telnet  or  Rlogin  server  and/or  PTY  driver). 

OTHER  FEATURES 

C-Kermit  includes  features  too  numerous  to  be  explained  in  a  man  page.  For  further  information  about 
connection  establishment,  modem  dialing,  networks,  terminal  connection,  key  mapping,  logging,  file 
transfer  options  and  features,  troubleshooting,  client/server  operation,  character-set  translation  during  ter- 
minal connection  and  file  transfer,  "raw"  up-  and  downloading  of  files,  macro  construction,  script  program- 
ming, convenience  features,  and  shortcuts,  plus  numerous  tables,  examples,  and  illustrations,  please  con- 
sult Using  C-Kermit. 

GETTING  HELP 

C-Kermit  has  extensive  built-in  help.  You  can  find  out  what  commands  exist  by  typing  ?  at  the  C-Kermit> 
prompt.  You  can  type  HELP  at  the  C-Kermit> prompt  for  "getting-started"  message,  or  HELP  followed  by 
the  name  of  a  particular  command  for  information  about  that  command,  for  example: 

help  send 
help  set  file 

You  can  type  ?  anywhere  within  a  command  to  get  brief  help  about  the  current  command  field.  You  can 
also  type  the  INTRO  command  to  get  a  brief  introduction  to  C-Kermit,  and  the  MANUAL  command  to 
access  this  (or  another)  manual  page.  Finally,  you  can  use  the  SUPPORT  command  for  instructions  on 
obtaining  technical  support. 

ENTERING  COMMANDS 

You  can  use  upper  or  lower  case  for  interactive-mode  commands,  but  remember  that  UNIX  filenames  are 
case-sensitive.  You  can  abbreviate  commands  as  long  as  the  abbreviation  matches  only  one  possibility. 
Whiletyping  a  command,  you  can  use  the  foil  owing  editing  characters: 

Delete,  Backspace,  or  Rubout  erases  the  rightmost  character. 
Ctrl-W  erases  the  rightmost  "word". 
Ctrl-U  erases  the  current  command  line. 
Ctrl-R  redisplays  the  current  command. 

Ctrl-P  recalls  a  previous  command  (scrolls  back  in  command  buffer). 
Ctrl-N  scrolls  forward  in  a  scrolled-back  command  buffer. 
Ctrl-C  cancels  the  current  command. 

Tab,  Esc,  or  Ctrl-I  tries  to  complete  the  current  keyword  or  filename. 
?  gives  help  about  the  current  field. 

To  enter  the  command  and  make  it  execute,  press  the  Return  or  Enter  key. 

BACKSLASH  NOTATION 

Within  an  interactive  command,  the  \  character  (backslash)  is  a  prefix  used  to  enter  special  quantities, 
including  ordinary  characters  that  would  otherwise  be  illegal.  At  the  end  of  a  line,  \  or  -  (dash)  makes  the 
next  line  a  continuation  of  the  current  line.  Other  than  that,  the  character  following  the  \  identifies  what 
the  special  quantity  is: 


d  (or  D) 
o  (or  O) 
x  (or  X) 


% 
& 
$ 


v  (or  V) 
f  (orF) 
s  (or  S) 


A  user-defined  simple  (scalar)  variablesuch  as\  %a  or  \  %1 

an  array  reference  such  as\  &a[3] 

an  environment  variablesuch  as\  $(TERM) 

a  built-in  variablesuch  as\  v(time) 

a  function  such  as\  Fsubstring(\  %a,3,2) 

compact  substring  notation,  macronames,  I i ke \  s(foo[3:12]) 

compact  substring  notation,  all  variables,  I i ke \  :(a[3:12]) 

a  decimal  (base  10)  number  (1  to  3  digits,  0..255)  such  as\  d27 

an  octal  (base8)  number  (1  to  3  digits,  0.311)  such  as\  o33 

a  hexadecimal  (base  16)  number  (2  digits,  00.. ff)  I i ke \  xlb 
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\ 

b(or  B) 

I  (or  L) 

n  (or  N) 

a  decimal  digit 

{} 

anything  else: 


the  backslash  character  itself 

the  BREAK  signal  (OUTPUT  command  only) 

a  Long  BREAK  signal  (OUTPUT  only) 

a  NUL  (0)  character  (OUTPUT  only) 

a  1-,  2-,  or  3-digit  decimal  number,  such  as\  27 

used  for  grouping,  e.g.  \  -(27}123 

following  character  taken  literally. 


Note  that  numbers  turn  into  the  character  with  that  binary  code  (0-255),  so  you  can  use\7  for  a  bell,  \13 
for  carriage  return,  \10  for  linefeed.  For  example,  to  have  C-Kermit  send  a  BELL  to  your  screen,  type: 

echo  \7 
COMMAND  LIST 

Thecommands  most  commonly  used,  and  important  for  beginners  to  know,  are  marked  with  "*": 


Program  Management: 

BACK 
BROWSE 

*  CD 
PWD 
CHECK 
CLOSE 
COMMENT 
COPYRIGHT 
DATE 

*  EXIT 

*  HELP 

*  INTRO 
KERMIT 
LOG 
PUSH 
QUIT 
REDO 
RUN 

SET  COMMAND 
SET  PROMPT 
SET  EXIT 
SHOW  EXIT 
SHOW  FEATURES 
SHOW  VERSIONS 
SUPPORT 
SUSPEND 

*  SHOW 

*  TAKE 
VERSION 
Z 

*  Ctrl-C 
Ctrl-Z 

;  or  # 
!  or  @ 
< 


Return  to  previous  directory. 

I  nvoke  Web  browser. 

Change  Directory 

Print  Working  Directory. 

See  if  the  given  feature  is  configured. 

Close  a  connection  or  a  log  or  other  local  file. 

I  ntroduce  a  full-linecomment. 

Display  copyright  notice. 

Display  date  and  time. 

Leave  the  program,  return  to  UNIX. 

Display  a  help  message  for  a  given  command. 

Print  a  brief  introduction  to  C-Kermit. 

Give  command-line  options  at  the  prompt. 

Open  a  log  file  -  debugging,  packet,  session,  transaction. 

Invoke  local  system's  interactive  command  interpreter. 

Synonym  for  EXIT. 

Re-execute  a  previous  command. 

Run  a  program  or  system  command. 

Command-related  parameters:  bytesize,  recall  buffer  size. 

The  C-Kermit  programs'  interactive  command  prompt. 

Items  related  to  C-Kermit's  action  upon  exit  or  SET  LI  NE/HOST. 

Display  SET  EXIT  parameters. 

Show  features  that  C-Kermit  was  built  with. 

Show  version  numbers  of  each  source  module. 

Find  out  how  to  get  technical  support. 

Suspend  Kermit  (use  only  if  shell  supports  job  control!). 

Display valuesof  SET  parameters. 

Execute  commands  from  a  file. 

Display  the  C-Kermit  program  version  number. 

Synonym  for  SUSPEND. 

Interrupt  a  C-Kermit  command  in  progress. 

Synonym  for  SUSPEND. 

I  ntroduce  a  full-lineor  trailing  comment. 

Synonym  for  RUN. 

Synonym  for  REDIRECT. 


Connection  Establishment  and  Release: 


*  DIAL 
PDIAL 

*  LOOKUP 
ANSWER 

*  HANGUP 
EIGHTBIT 
PAD 
PING 


Dial  a  telephone  number. 

Partially  dial  a  telephone  number. 

Lookup  a  phone  number,  test  dialing  rules. 

Wait  for  a  phone  call  and  answer  it  when  it  comes. 

Hang  up  the  phone  or  network  connection. 

Shortcut  to  set  all  i/o  to  8  bits. 

Command  for  X.25  PAD  (SunOS  /  Solaris/ VOS  only). 
Check  status  of  remote  TCP/I  P  host. 
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REDIAL 

LOG  CONNECTIONS 

REDIRECT 

PIPE 

SET  CARRIER 

*  SET  DIAL 

*  SET  FLOW 

*  SET  HOST 

*  SET  LINE 
SET  PORT 

*  SET  MODEM  TYPE 

*  SET  NETWORK 
SET  TCP 

SET  TELNET 
SET  X.25 
SET  PAD 

*  SET  PARITY 

*  SET  SPEED 
SET  SERIAL 
SET  STOP-BITS 
SHOW  COMM 
SHOW  CONN 
SHOW  DIAL 
SHOW  MODEM 
SHOW  NETWORK 

*  TELNET 
RLOGIN 
TELOPT 
CLOSE 

Terminal  Connection: 

*  C 

*  CONNECT 
LOG  SESSION 
SET  COMMAND 

*  SET  DUPLEX 
SET  ESCAPE 
SET  KEY 

SET  TERMINAL 
SHOW  ESCAPE 
SHOW  KEY 
SHOW  TERMINAL 

*  Ctrl-\ 


File  Transfer: 

ADD  SEND-LIST 

ADD  BINARY-PATTERNS 

ADD  TEXT-PATTERNS 

ASSOCIATE 

LOG  SESSION 

*  SEND 
MSEND 
MOVE 
MMOVE 
MAIL 
RESEND 
PSEND 

*  RECEIVE 


Dial  the  meet  recently  DIALed  number  again. 
Keep  a  record  of  each  connection. 

Redirect  standard  i/o  of  command  to  communication  connection. 
Make  a  connection  through  an  external  command  or  program. 
Treatment  of  carrier  on  terminal  connections. 
Parameters  related  to  modem  dialing. 

Communication  line  flow  control:  AUTO,  RTS/CTS,  XON/XOFF,  etc. 
Specify  remote  network  host  name  or  address. 
Specify  serial  communication  device  name,  Nke/dev/culOpO. 
Synonym  for  SET  LINE. 

Specify  type  of  modem  on  SET  LINE  device,  like  USR. 
Network  type,  X.25  (SunOS  /  Solaris/ VOS  only)  or  TCP/I  P. 
Specify  TCP  protocol  options  (advanced). 
Specify  TELNET  protocol  options. 

Specify  X.25  connection  parameters  (SunOS  /  Solaris  /  VOS  only). 

X.25  X. 3  PAD  parameters  (SunOS  /  Solaris/ VOS  only). 

Character  parity  (none,  even,  etc.)  for  communications. 

Serial  communication  device  speed,  e.g.  2400,  9600,  57600. 

Set  serial  communications  data  size,  parity,  stop  bits. 

Set  serial  communications  stop  bits. 

Display  all  communications  settings. 

Display  info  a  bout  current  connection. 

Display  SET  DIAL  values. 

Display  modem  type,  signals,  etc. 

Display  network-related  items. 

=  SET  NETWORK  TCP/IP,  SET  HOST  CONNECT. 
Makes  an  RLOGI N  connection  (requires  privilege). 
Send  a  TELNET  option  negotiation  (advanced). 
Close  the  current  connection. 


Special  abbreviation  for  CONNECT. 

Establish  a  terminal  connection  to  a  remote  computer. 

Record  terminal  session. 

Bytesize  between  C-Kermit  and  your  keyboard  and  screen. 

Specify  which  side  echoes  during  CONNECT. 

Prefix  for  "escape  commands"  during  CONNECT. 

Key  redefinitions  in  CONNECT  mode. 

Terminal  connection  items:  bytesize,  character-set,  echo,  etc. 

Display  current  CONNECT-mode  escape  character. 

Display  keycode  and  assigned  value  or  macro. 

Display  SET  TERMINAL  items. 

CONNECT-mode  escape  character,  followed  by  another  character: 
C  to  return  to  C-Kermit>  prompt. 
B  to  send  BREAK  signal. 
?  to  see  other  options. 


Add  a  file  specification  to  the  SEND-LIST. 
Add  a  pattern  to  the  binary  file  pattern  list. 
Add  a  pattern  tothetext  filepattern  list. 
A  file  character-set  with  a  transfer  character-set. 
Download  a  file  with  no  error  checking. 
Send  a  file  or  files. 

MultipleSEND  -  accepts  a  list  of  files,  separated  by  spaces. 
SEND  and  then  delete  source  fi I e(s)  if  successful. 
Multiple  MOVE  -  accepts  a  list  of  files,  separated  by  spaces. 
SEND  a  file  to  other  Kermit,  to  be  delivered  as  e-mail. 
Continuea  incomplete  SEND. 
Send  part  of  a  file. 

Passively  wait  for  files  to  arrive  from  other  Kermit. 
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*  R 

*  S 
GET 
MGET 
REGET 
G 

FAST 

CAUTIOUS 
ROBUST 
SET  ATTRI B 

*  SET  BLOCK 
SET  BUFFERS 
SET  PREFIX 
SET  DELAY 

SET  DESTINATION 

*  SET  FILE 

*  SET  RECEIVE 
SET  REPEAT 
SET  RETRY 
SET  SEND 

SET  HANDSHAKE 

SET  LANGUAGE 

PATTERNS 

SET  SESSION-LOG 

SET  TRANSFER 

SET  TRANSMIT 

SET  UNKNOWN 

*  SET  WINDOW 
SHOW  ATTRI  B 
SHOW  CONTROL 

*  SHOW  FILE 
SHOW  PROTOCOL 
SHOW  LANGUAGE 
SHOW  TRANSMIT 

*  STATISTICS 
TRANSMIT 
XMIT 

SEND  Command  switches: 

/AS-NAME: 

/AFTER: 

/BEFORE: 

/BINARY 

/COMMAND 

/DELETE 

/EXCEPT: 

/FILTER: 

/FILENAMES: 

/LARGER-THAN: 

/LIST: 

/MAIL: 

/MOVE -TO: 

/NOT -AFTER: 

/NOT-BEFORE: 

/PATHNAMES: 

/PRINT: 

/PROTOCOL: 

/QUIET 

/RECOVER 

/RECURSIVE 

/RENAME-TO: 


Special  abbreviation  for  RECEIVE. 

Special  abbreviation  for  SEND. 

Ask  server  to  send  the  specified  file(s). 

LikeGET  but  accepts  a  list  of  files. 

Continue  a  incomplete  download  from  a  server. 

Special  abbreviation  for  GET. 

Shortcut  for  fast  file-transfer  settings. 

Shortcut  for  medium  file-transfer  settings. 

Shortcut  for  conservative  file-transfer  settings. 

Control  transmission  of  file  attributes. 

Choose  error-checking  level,  1,  2,  or  3. 

Size  of  send  and  receive  packet  buffers. 

Which  control  characters  to  "unprefix"  during  filetransfer. 

How  long  to  wait  before  sending  first  packet. 

DISK,  PRINTER,  or  SCREEN  for  incoming  files. 

Transfer  mode  (type),  character-set,  collision  action,  etc 

Parameters  for  inbound  packets:  packet-length,  etc. 

Repeat-count  compression  parameters. 

Packet  retransmission  limit. 

Parameters  for  outbound  packets:  length,  etc. 

Communication  line  half-duplex  packet  turnaround  character. 

Enable  language-specific  character-set  translations. 

Turn  off  filename-pattern-based  text/binary  mode  switching. 

File  type  for  session  log,  text  or  binary. 

Filetransfer  parameters:  character-set,  display,  etc. 

Control  aspects  of  TRANSMIT  command  execution. 

Specify  handlingof  unknown  character  sets. 

Filetransfer  packet  window  size,  1-31. 

Display  SET  ATTRIBUTE  values. 

Display  control-character  prefixing  map. 

Display  file-related  settings. 

Display  protocol -related  settings. 

Display  language-related  settings. 

Display  SET  TRANSMIT  values. 

Display  statistics  about  most  recent  filetransfer. 

Send  a  file  with  no  error  checking. 

Synonym  for  TRANSMIT. 


Name  to  send  file  under. 
Send  files  modified  after  date-time. 
Send  files  modified  before  date-time. 
Send  in  binary  mode. 

Send  from  standard  output  of  a  command. 

Delete  file  after  successfully  sending. 

Don't  send  files  whose  names  match  given  pattern(s). 

Pass  file  contents  through  given  filter  program. 

Specify  how  to  send  filenames. 

Send  files  larger  than  given  size. 

Send  files  whose  names  are  listed  in  given  file. 

Send  file(s)  as  e-mail  to  given  address. 

Move  source  file  to  given  directory  after  successfully  sending. 

Send  files  modified  not  after  given  date-time. 

Send  files  modified  not  before  given  date-time. 

Specify  how  to  send  pathnames. 

Send  files  to  be  printed. 

Send  files  using  given  protocol. 

Don't  display  file-transfer  progress. 

Recover  interrupted  transfer  from  point  of  failure. 

Send  a  di  rectory  tree. 

Rename  files  as  specified  after  successfully  sending. 
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/SMALLER-THAN: 
/STARTI NG-AT: 
/SUBJ  ECT: 
/TEXT 


Send  files  smaller  than  given  size. 
Send  file  starting  at  given  byte  number. 
Subject  for  SEND /MAIL. 
Send  i  n  text  mode. 


GET  and  RECEIVE 

/AS-NAME: 

/BINARY 

/COMMAND: 

/EXCEPT: 

/FILENAMES: 

/FILTER: 

/MOVE -TO: 

/PATHNAMES: 

/PROTOCOL: 

/RENAME-TO: 

/QUIET: 

/TEXT 


Command  switches: 

Store  incoming  file  under  given  name. 

Receive  in  binary  mode  if  transfer  mode  not  specified. 

Send  incoming  file  data  to  given  command. 

Don't  accept  incoming  files  whose  names  match. 

How  to  treat  incoming  file  names. 

Filter  program  for  incoming  file  data. 

Where  to  move  a  file  after  successful  receipt. 

H  ow  to  treat  i  ncomi  ng  path  names. 

Protocol  to  use  for  receiving  (RECEIVE  only). 

New  name  for  file  after  successful  receipt. 

Suppress  file-transfer  display. 

Receive  in  text  mode  if  transfer  mode  not  specified. 


Switches  only  for  GET: 

/DELETE 

/RECOVER 

/RECURSIVE 

File  Management: 

*  CD 

*  PWD 
COPY 

*  DELETE 

*  DIRECTORY 
EDIT 
MKDIR 
PRINT 
PURGE 
RENAME 
RMDIR 

SET  PRINTER 
SPACE 

SHOW  CHARACTER-SETS 

TRANSLATE 

TYPE 

TYPE  /PAGE 
XLATE 

Client/Server  Operation: 

BYE 

DISABLE 
E-PACKET 
ENABLE 
FINISH 

G 

GET 
QUERY 
RETRIEVE 
REMOTE  xxx 
REMOTE  ASSIGN 
REMOTE  CD 
REMOTE  COPY 
REMOTE  DELETE 
REMOTE  DIR 
REMOTE  EXIT 


Tells  server  to  delete  each  file  after  successful  transmission. 
Resume  interrupted  filetransfer  from  point  of  failure. 
Tells  server  to  send  a  directory  tree. 


Change  Directory. 

Display  current  working  directory. 

Copy  a  file. 

Delete  a  file  or  files. 

Display  a  directory  listing. 

Edit  a  file. 

Create  a  directory. 

Print  a  local  file  on  a  local  printer. 

Remove  backup  files. 

Change  the  name  of  a  local  file. 

Remove  a  directory. 

Choose  printer  device. 

Display  current  disk  space  usage. 

Display  character-set  translation  info. 

Translate  a  local  file's  character  set. 

Display  a  file  on  the  screen. 

Display  a  file  on  the  screen,  pausing  after  each  screenful. 
Synonym  for  TRANSLATE. 


Terminate  a  remote  Kermit  server  and  log  out  its  job. 
Disallow  access  to  selected  features  during  server  operation. 
Send  an  Error  packet. 

Allow  access  to  selected  features  during  server  operation. 

I  nstruct  a  remote  Kermit  server  to  exit,  but  not  log  out. 

Special  abbreviation  for  GET. 

Get  files  from  a  remote  Kermit  server. 

(Same  as  RE  MOTE  QUERY) 

Like  GET  but  server  deletes  files  after. 

Command  for  server,  can  be  redirected  with  >or  |  . 

(RASG)  Assign  a  variable. 

(RCD)  Tell  remote  Kermit  server  to  change  its  directory. 
(RCOPY)  Tell  server  to  copy  a  file. 
(RDEL)  Tell  server  to  delete  a  file. 
(RDI R)  Ask  server  for  a  directory  listing. 
(REXIT)  Ask  the  server  program  to  exit. 
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REMOTE  HELP 
REMOTE  HOST 
REMOTE  KERMIT 
REMOTE  LOGIN 
REMOTE  LOGOUT 
REMOTE  MKDIR 
REMOTE  PRINT 
REMOTE  PWD 
REMOTE  QUERY 
REMOTE  RENAME 
REMOTE  RMDIR 
REMOTE  SET 
REMOTE  SPACE 
REMOTE  TYPE 
REMOTE  WHO 
SERVER 
SET  SERVER 
SHOW  SERVER 


(RHELP)  Ask  server  to  send  a  help  message. 

(RHOST)  Ask  server  to  ask  its  host  to  execute  a  command. 

(RKER)  Send  an  interactive  Kermit  command  to  the  server. 

Authenticate  yourself  to  a  remote  Kermit  server. 

Log  out  from  a  Kermit  server  previously  LOG  I  N'd  to. 

(RMKDIR)Tell  the  server  to  create  a  directory. 

(RPRI  NT)  Print  a  local  file  on  the  server's  printer. 

(RPWD)  Ask  server  to  reveal  its  current  (working)  directory. 

(RQUERY)  Get  value  of  a  variable. 

(RRENAME)  Tell  server  to  rename  a  file. 

(RRMDIR)  Tell  server  to  remove  a  directory. 

Send  a  SET  command  to  a  remote  server. 

Ask  server  how  much  disk  space  it  has  left. 

Ask  server  to  display  a  file  on  your  screen. 

Ask  server  for  a  "who"  or  "finger"  listing. 

Be  a  Kermit  server. 

Parameters  for  server  operation. 

Show  SET  SERVER,  ENABLE/DISABLE  items. 


Script  programming: 


ASK 

Prompt  the  user,  store  user's  reply  in  a  variable. 

ASKQ 

Like  ASK,  but  does  not  echo  (useful  for  passwords). 

ASSERT 

Evaluatecondition  and  set  SUCCESS/FAILURE  accordingly. 

ASSIGN 

Assign  an  evaluated  string  to  a  variableor  macro. 

CLEAR 

Clear  communication  device  input  buffer  or  other  item. 

CLOSE 

Close  the  connection,  or  a  log  or  other  file. 

DECLARE 

Declare  an  array. 

DECREMENT 

Subtract  one  (or  other  number)  from  a  variable. 

DEFINE 

Define  a  variableor  macro. 

DO 

Execute  a  macro  ("DO"  can  be  omitted). 

ECHO 

Display  text  on  the  screen. 

ELSE 

Used  with  IF. 

END 

A  command  file  or  macro. 

EVALUATE 

An  arithmetic  expression. 

FAIL 

Set  FAILURE. 

FOPEN 

Open  a  local  file. 

FREAD 

Read  from  a  fileopened  with  FOPEN. 

FWRITE 

Write  to  an  FOPEN'd  file. 

FSEEK 

Seeks  to  given  position  in  FOPEN'd  file. 

FCLOSE 

Closean  FOPEN'd  file. 

FOR 

Execute  commands  repeatedly  in  a  counted  loop. 

FORWARD 

GOTO  in  theforward  direction  only. 

GETC 

1  ssue  a  prompt,  get  one  character  from  keyboard. 

GETOK 

Ask  question,  get  Yes  or  No  answer,  set  SUCCESS  or  FAI  LURE. 

GOTO 

Go  to  a  labeled  command  in  a  command  file  or  macro. 

IF 

Conditionally  execute  the  foil  owing  command. 

INCREMENT 

Add  one  (or  other  number)  to  a  variable. 

INPUT 

Match  characters  from  another  computer  against  a  given  text. 

LOCAL 

Declares  local  variables  in  a  macro. 

MINPUT 

Like  INPUT,  but  allows  several  match  strings. 

MSLEEP 

Sleep  for  given  number  of  milliseconds. 

OPEN 

Open  a  local  filefor  reading  or  writing. 

OUTPUT 

Send  text  to  another  computer. 

0 

Special  abbreviation  for  OUTPUT. 

PAUSE 

Do  nothing  for  a  given  number  of  seconds. 

READ 

Read  a  line  from  a  local  file  intoa  variable. 

REINPUT 

Reexamine  text  previously  received  from  another  computer. 

RETURN 

Return  from  a  user-defined  function. 

SCREEN 

Screen  operations  -  clear,  position  cursor,  etc. 

SCRIPT 

Execute  a  UUCP-style  login  script. 

SET  ALARM 

Set  a  timer  to  be  used  with  IF  ALARM;  SHOW  ALARM  shows  it. 
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SET  CASE 

Treatment  of  alphabetic  case  in  string  comparisons. 

SET  COMMAND 

QUOTING  turns  on/off  interpretation  of  backslash  notation. 

SET  COUNT 

For  counted  loops. 

SET  INPUT 

Control  behavior  of  INPUT  command. 

SET  MACRO 

Control  aspects  of  macro  execution. 

SET  TAKE 

Control  aspects  of  TAKE  file  execution. 

SHIFT 

Shift  macro  arguments  left  the  given  number  of  places. 

SHOW  ARGUMENTS 

Display  arguments  to  current  macro. 

SHOW  ARRAYS 

Display  information  about  active  arrays. 

SHOW  COUNT 

Display  current  COUNT  value. 

SHOW  FUNCTIONS 

List  names  of  available\  f()  functions. 

SHOW  GLOBALS 

List  defined  global  variables\  %a..\  %z. 

SHOW  MACROS 

List  one  or  more  macro  definitions. 

SHOW  SCRIPTS 

Show  script-related  settings. 

SHOW  VARIABLES 

Display  values  all  \  v()  variables. 

SLEEP 

Sleep  for  given  number  of  seconds. 

SORT 

Sort  an  array  (many  options). 

STATUS 

Show  SUCCESS  or  FAI  LURE  of  previous  command. 

STOP 

Stop  executing  macro  or  command  file,  return  to  prompt. 

SUCCEED 

Set  SUCCESS. 

SWITCH 

Execute  selected  command(s)  based  on  value  of  variable. 

TAKE 

Execute  commands  from  a  file. 

UNDEFINE 

Undefine  a  variable. 

WAIT 

Wait  for  the  specified  modem  signals. 

WHILE 

Execute  commands  repeatedly  whilea  condition  istrue. 

WRITE 

Write  material  to  a  local  file. 

WRITE-LI NE 

Write  a  line  (record)  to  a  local  file. 

WRITELN 

Synonym  for  WRITE-LI  NE. 

XECHO 

Like  ECHO  but  noCRLF  at  end. 

XI F 

Extended  IF  command. 

BUILT-IN  VARIABLES 

Built-in  variables  are  referred  to  by  \  v(name),  can  be  used  in  any  command,  usually  used  in  script  pro- 
gramming. They  cannot  be  changed.  Type  SHOW  VARIABLES  for  a  current  list. 


v(argc) 

Number  of  arguments  in  current  macro 

v(args) 

Number  of  program  command-line  arguments 

v(blockcheck) 

Current  SET  BLOCK-CHECK  type 

v(browser) 

Current  Web  browser 

v(browsopts) 

Current  Web  browser  options 

v(browsurl) 

M ost  recent  Web  browser  site  (U RL ) 

v(byteorder) 

H  ardware  byte  order 

v(charset) 

Current  file  character-set 

v(cmdbufsize) 

Size  of  command  buffer 

v(cmdf  i  1  e) 

Name  of  current  command  file,  if  any 

v(cmdlevel) 

Current  command  level 

v(cmdsource) 

Where  command  are  currently  coming  from,  macro,  file,  etc. 

v(cols) 

Number  of  screen  columns 

v(connection) 

Connection  type:  serial,  tcp/ip,  etc. 

v(count) 

Current  COUNT  value 

v(cps) 

Speed  of  most  recent  file  transfer  in  chars  per  second 

v(cpu) 

CPU  type  C-Kermit  was  built  for 

v(crcl6) 

16-bit  CRC  of  most  recent  filetransfer 

v(ctty) 

Devi  ce  name  of  control  1  i  ng  termi  nal 

v(d$ac) 

SET  DIAL  AREA-CODE  value 

v(d$cc) 

SET  DIAL  COUNTRY-CODE  value 

v(d$ip) 

SET  DIAL  INTL-PREFIX  value 

v(d$lc) 

SET  DIAL  LD-PREFIX  value 

v(d$px) 

SET  DIAL  PBX-EXCHANGE  value 

v(date) 

Date  as  8  Feb  1993 

v(day) 

Day  of  week 
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\v(dial  count) 

Current  value  of  DIAL  retry  counter 

\  v(dialnumber) 

Phone  number  most  recently  dialed 

\  v(dialresult) 

Most  recent  dial  result  message  or  code  from  modem 

\v(dial  status) 

Return  code  from  DIAL  command  (0  =OK,  22  =BUSY,  etc) 

\  v(dialsuffix) 

Current  SET  DIAL  SUFFIX  value 

\  v(dialtype) 

Code  for  type  of  cal  1  most  recently  placed 

\  v(di  rectory) 

Current/default  directory 

\  v(download) 

Current  download  directory  if  any 

\  v(editor) 

Your  preferred  editor 

\  v(editfile) 

File  most  recently  edited 

\  v(editopts) 

Options  for  editor 

\  v(errno) 

Current  "errno"  (system  error  number)  value 

\  v(errstring) 

Error  message stri ng  associated  with  errno 

\  v(escape) 

Decimal  ASCII  val  ue  of  CONN  ECT-mode  escape  character 

\  v(eval  uate) 

Result  of  most  recent  EVALUATE  command 

\  v(exitstatus) 

Current  EXIT  status  (0  =  good,  nonzero  =something failed) 

\  v(filename) 

Name  of  file  currently  being  transferred 

\  v(filenumber) 

Number  of  file  currently  being  transferred  (1  =  first,  etc) 

\  v(filespec) 

Filespec given  in  most  recent  SEND/RECEIVE/GET  command 

\  v(fsize) 

Size  of  file  most  recently  transferred 

\  v(ftype) 

SET  FILE  TYPE  value  (text,  binary) 

\  v(herald) 

C-Kermit's  program  herald 

\  v(home) 

Home  directory 

\  v(host) 

Computer  host  name  (computer  where  C-Kermit  is  running) 

\  v(hwparity) 

SET  PARITY  HARDWARE  setting  (if  any) 

\  v(input) 

Current  INPUT  buffer  contents 

\  v(inchar) 

Character  most  recently  INPUT 

\  v(incount) 

How  many  characters  arrived  during  last  1 NPUT 

\  v(inidir) 

Directory  where  initialization  file  was  found 

\  v(inmatch) 

[M]INPUT  material  that  matched  given  \fpattern(). 

\  v(instatus) 

Status  of  most  recent  1  NPUT  command 

\  v(i  nti  me) 

How  long  it  took  most  recent  INPUT  to  succeed  (msec) 

\  v(inwait) 

Most  recent  [M]l NPUT  time  limit 

\  v(ipaddress) 

1 P  address  of  C-Kermit's  computer  if  known 

\  v(kbchar) 

Keyboard  character  that  interrupted  PAUSE,  INPUT,  etc. 

\  v(line) 

Current  communications  device,  set  by  LI  NE  or  HOST 

\  v(local) 

0  if  in  remote  mode,  1  if  in  local  mode 

\  v(lockdir) 

UUCP  lockfiledi rectory  on  this  platform 

\  v(lockpid) 

Process  ID  found  in  lockfile  when  port  is  in  use 

\  v(macl  evel) 

Current  macro  stack  level 

\  v(macro) 

Name  of  currently  executing  macro,  if  any 

\  v(math_e) 

Floating-point  constant  e 

\  v(math_pi) 

Floating-point  constant  pi 

\  v(mathprecision) 

Floating  point  number  precision  (digits) 

\  v(minput) 

Result  of  most  recent  Ml  NPUT  command 

\  v(model) 

Computer  hardware  model  if  known 

\  v(modem) 

Current  modem  type 

\  v(m_aa_off) 

Modem  command  to  turn  autoanswer  off 

\  v(maaon) 

Modem  command  to  turn  autoanswer  on 

\  v(mxxxxx) 

(many  other  modem  commands) 

\  v(msigxx) 

Value  of  modem  signal  xx 

\  v(name) 

Name  by  which  C-Kermit  was  called  (kermit,  wermit,  etc) 

\  v(ndate) 

Current  date  as  19930208  (yyyymmdd) 

\  v(nday) 

Numeric  day  of  week  (0  =  Sunday) 

\  v(newline) 

System-independent  newline character  or  sequence 

\  v(ntime) 

Current  local  time  in  seconds  since  midnight  (noon  =43200) 

\  v(osname) 

Operating  System  name 

\  v(osrelease) 

Operating  System  release 

\  v(osversion) 

Operating  System  version 

\  v(packetlen) 

Current  SET  RECEIVE  PACKET-LENGTH  value 

\  v(parity) 

Current  parity  setting 

Section  1-376 


-10- 


HP-UX  Release  Hi:  December  2000 


kermit(l) 


(HP-UX  C-Kermit) 


kermit(l) 


\  v(pexitstat) 

Exit  status  of  most  recently  forked  process 

\  v(pid) 

C-Kermit's  process  1 D 

\  v(platform) 

Specific  machine  and/or  operating  system 

\  v(program) 

Name  of  this  program  ("C-Kermit") 

\  v(protocol) 

Currently  selected  file  transfer  protocol 

\v(p  8bit) 

Current  8th-bit  prefix  (Kermit  protocol) 

\v(p_ctl) 

Current  control -character  prefix  (Kermit  protocol) 

\  v(p_rpt) 

Current  repeat-count  prefix  (Kermit  protocol) 

\  v(query) 

Result  of  most  recent  REMOTE  QUERY  command 

\  v(return) 

Most  recent  RETURN  value 

\  v(rows) 

Number  of  rows  on  the  terminal  screen 

\  v(sendlist) 

Number  of  entries  in  SEND-LIST 

\  v(serial) 

Seri al  port  setti  ngs  i  n  8N 1  format 

\  v(speed) 

Current  speed,  if  known,  or  "unknown" 

\  v(startup) 

Current  directory  when  C-Kermit  was  started 

\  v(status) 

Oor  1  (SUCCESS  or  FAILURE  of  previous  command) 

\  v(sysid) 

Code  for  platformID  of  C-Kermit's  computer  (U1=UNIX) 

\  v(system) 

UNIX  (name of  operating  system  family) 

\  v(terminal) 

Terminal  type 

\  v(test) 

C-Kermit  test  version,  if  any  (e.g.  Beta. 10) 

\  v(textdir) 

Where  C-Kermit  thinks  its  text  files  are 

\  v(tfsize) 

Total  size  of  file  group  most  recently  transferred 

\  v(ti  me) 

Time  as  13:45:23  (hh:mm:ss) 

\  v(tmpdir) 

Temporary  directory 

\  v(trigger) 

Most  recent  string  to  trigger  return  from  CONNECT 

\  v(ttyfd) 

File  descriptor  of  current  communication  device 

\  v(ty_xx) 

Used  internally  by  TYPE 

\  v(userid) 

User  ID  of  person  running  C-Kermit 

\  v(version) 

Numeric  version  of  Kermit,  e.g.  501190. 

\  v(window) 

Current  window  size  (SET  WINDOW  value) 

\  v(xferstatus) 

Status  of  most  recent  file  transfer 

\  v(xfermsg) 

Error  message,  if  any,  terminating  most  recent  transfer 

\  v(xferxxx) 

Various  statistics  from  last  filetransfer. 

\  v(xprogram) 

C-Kermit 

\  v(xversion) 

Same  as  \  v(version) 

BUILT-IN  FUNCTIONS 

Bui Itin  functions  are  invoked  as\  Fname(args),  can  be  used  in  any  command,  and  are  usually  used  in  script 
programs.  Type  SHOW  FUNCTIONS  for  a  current  list.  Type  "help  function  <name>"  for  a  description  of 
the  arguments  and  return  value,  for  example,  help  function  basename. 

COMMAND  LINE  OPTIONS 

C-Kermit  accepts  commands  (or  "options")  on  the  command  line,  in  the  time-honored  UNIX  style.  Alpha- 
betic case  is  significant.  All  options  are  optional.  If  one  or  more  action  options  are  included,  Kermit  exits 
immediately  after  executing  the  command-line  options,  otherwise  it  enters  interactive  command  mode. 

kermit  [filename]  [-x  arg  [-x  arg]...[-yyy]...]] 
where: 

filename  is  the  name  of  a  command  file  to  execute, 
-x  is  an  option  requiring  an  argument, 
-y  an  option  with  no  argument. 


Actions: 

-s  files 

send  files 

-s  - 

send  files  from  stdin 

-r 

receive  files 

-k 

receive  files  to  stdout 

-X 

enter  server  mode 

-0 

like  -x  but  exits  after  one  transaction 

-f 

finish  remote  server 
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-g  files  get  remote  files  from  server  (quote  wildcards) 

-G  files  like-g  but  sends  file  to  standard  output 

-a  name  alternate  file  name,  used  with  -s,  -r,  -g 

-c  connect  (before  file  transfer),  used  with  -I  or  -j 

-n  connect  (after  file  transfer),  used  with  -I  or  -j 

Settings: 

-I  line  communication  linedevice (to makea  serial  connection) 

-I  n  open  file  descriptor  of  communication  device 

-j  host  TCP/I  P  network  host  name  (to  make  a  network  connection) 

-J  host  connect  MkeTELNET,  exit  when  connection  closes 

-I  n  open  file  descriptor  of  TCP/IP  connection  (n  =  number) 

-X  X.25  network  address 

-Z  open  file  descriptor  of  X.25  connection 

-on  X.25  closed  user  group  call  info 

-u  X.25  reverse-charge  call 

-q  quiet  during  file  transfer 

-I  connection  is  reliable(e.g.  TCP  or  X.25) 

-8  8-bit  clean 

-0  100% transparency  in  CONNECT  mode  (and  no  escaping  back) 

-i  transfer  files  in  binary  mode 

-T  transfer  files  in  text  mode 

-P  send/accept  literal  path  (file)  names 

-b  bps  serial  linespeed,  e.g.  1200 

-m  name  modem  type,  e.g.  hayes 

-p  x  parity,  x  =e,o,m,s,  or  n 

-t  half  duplex,  xon  handshake 

-en  receive  packet-length 

-v  n  window  size 

-L  used  with  -s  to  select  recursive  directory  transfer 

-Q  Quick  file-transfer  settings 

-w  write  over  files  of  same  name,  do  not  backup  old  file 

-D  n  delay  n  seconds  before  sending  a  file 

-V  "manual  mode"  =  SET  FILE  PATTERNS  OFF,  SET  TRANSFER  MODE 

MANUAL. 

Other: 

-y  name  alternate  i nit  file  name 

-Y  Skip  init  file 

-R  Advise  C-Kermit  it  will  be  used  only  in  remote  mode 

-d  logdebuginfotofiledebug.log 

-S  Stay,  do  not  exit,  after  action  command 

-C  "cmds"  I  nteractive-mode  commands,  comma-separated 

-z  Force  foreground  operation 

-B  Force  background  (batch)  operation 

-h  print  command-lineoption  help  screen 

=  Ignore  all  text  that  follows 

Same  as  = 


COMMAND  LINE  EXAMPLES 

Remote-mode  example  (C-Kermit  is  on  the  far  end): 

kermit  -v  4  -i  -s  oof a. bin 

sendsfileoofa.bin  in  binary  mode  (-i)  using  a  window  size  of  4  (-v  4). 

Local-mode  example  (C-Kermit  makes  the  connection): 

kermit  -1  /dev/tty0p0   -b  19200  -c  -r  -n 

makes  a  19200-bps  direct  connection  out  through  /dev/tty0p0,  CONNECTS  (-c)  so  you  can  log  in  and, 
presumably  start  a  remote  Kermit  program  and  tell  it  to  send  a  file,  then  it  RECEIVES  the  file  (-r),  then  it 
CONNECTS  back  (-n)  so  you  can  finish  up  and  log  out. 
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For  dialingout,  you  must  specify  a  modem  type,  and  you  might  have  to  usea  different  device  name: 
kermit  -m  hayes  -1  /dev/culOpO   -b  2400  -c  -r  -n 

FILES 

$HOME/  .mykermrc  Your  personal  C-Kermit  customization  file. 

$HOME/  .kdd  Your  personal  dialing  directory. 

$HOME/  .  ksd  Your  personal  services  directory. 

/usr/share/lib/kermit/READ .ME  Overview  of  H P-UX  C-Kermit,  pleaseread 

/usr/share/lib/kermit/COPYING.  TXT      Copyright,  permissions,  disclaimer 
/usr/share/lib/kermit/ckermit .  ini      System-wide  initialization  file 
/usr/share/lib/kermit/ckermod.  ini      Sample  customization  file 
/usr/share/lib/kermit/ckermit .  kdd      Sample  dialing  directory 
/usr/share/lib/kermit/ckermit .  ksd      Sample  services  directory 
/usr/share/lib/kermit/ckermit2  .txt    Updates  to  "Using  C-Kermit"  2nd  Ed 
/usr/share/lib/kermit/ckcbwr  .  txt        C-Kermit  "beware"  file  -  hints  &  tips 
/usr/share/lib/kermit/ckubwr  .  txt        UNIX-specific  beware  file 
/usr/share/lib/kermit/ck*  .  txt  Other  plain-text  documentation 

/usr/share/lib/kermit/ckedemo .  ksc      Macros  from  "Using  C-Kermit" 
/usr/ share/lib/kermit/ckevt .  ksc  Ditto 
/usr/share/lib/kermit/ckepager  .  ksc    Alpha  pager  script 
/var/spool/locks/LCK.  .  *         ~  UUCP  lockfiles 

To  make  personalized  customizations,  copy  the  file  /usr/share/lib/kermit/ckermod.  ini 

file  to  your  home  directory,  make  any  desired  changes,  and  rename  it  to  .mykermrc . 

You  may  also  create  a  personalized  dialing  directory  like  the  sample  one  in 
/usr/share/lib/kermit/ckermit .  kdd.  Your  personalized  dialing  directory  should  be  stored  in 
your  home  directory  as  .kdd  and  your  personal  network  directory  as  .knd.  See  Chapters  5  and  6  of 
Using  C-Kermit  for  details. 

And  you  may  also  create  a  personalized  services  directory  like  the  sample  one  in 
/usr/share/lib/kermit/ckermit  .ksd.  Your  personalized  services  directory  should  be  stored  in 
your  home  di  rectory  as  .ksd.  See  Chapter  7  of  Using  C-Kermit  for  instructions. 

The  demonstration  files  MlustrateC-Kermit's  script  programming  constructs;  they  are  discussed  in  chapters 
17-19  of  the  book.  You  can  run  them  by  typing  the  appropriate  TAKE  command  at  the  C-Kermit>  prompt, 
for  example:  take  /usr/share/lib/kermit/ckedemo  .  ini. 

AUTHORS 

Frank  da  Cruz,  Columbia  University,  with  contributions  from  hundreds  of  other  volunteer  programmers  all 
over  the  world.  See  Acknowledgements  in  Using  C-Kermit. 
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DIAGNOSTICS 

The  diagnostics  produced  by  C-Kermit  itself  are  intended  to  be  self-explanatory.  In  addition,  every  com- 
mand returns  a  SUCCESS  or  FAILURE  status  that  can  be  tested  by  IF  FAILURE  or  IF  SUCCESS.  In 
addition,  the  program  itself  returns  an  exit  status  code  of  0  upon  successful  operation  or  nonzero  if  any  of 
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various  operations  failed. 
BUGS 

See  the  comp.protocols.kermit*  newsgroups  on  Usenet  for  discussion,  or  the  files,  ckcker.bwr  and 
ckuker.bwr,  for  a  list  of  bugs,  hints,  tips.  etc.  Report  bugs  via  e-mail  to  kermit- 
support@columbia.edu.  Visit  http://www.columbia.edu/kermit/support.html  for 
details  about  tech  support. 

CONTACTS 

For  more  information  about  Kermit  software  and  documentation,  visit  the  Kermit  Web  site: 

http : //www . Columbia . edu/kermit/ 

Or  write  to: 

The  Kermit  Project 
Columbia  University 
612  West  115th  Street 
New  York,  NY  10025-7221 
USA 

Or  send  e-mail  to  kermitgcolumbia .  edu.  Or  call  +1  212  854-3703.  Or  fax  +1  212  663-8202. 
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NAME 

keylogin  -  decrypt  and  store  secret  key  with  keyserv 

SYNOPSIS 

/usr/bin/keylogin  [  -r  ] 

DESCRIPTION 

The  keylogin  command  prompts  for  a  password,  and  uses  it  to  decrypt  the  user's  secret  key.  The  key 
may  be  found  in  the  /etc/publickey  file  (see  publicke/(4))  or  the  NIS  map  "publickey. byname"  or  the 
NIS+table  "cred.orgdir"  in  the  user's  home  domain.  The  sources  and  their  lookup  order  are  specified  in 
the  /etc/nsswitch .  conf  file  (see  nsswitch.conf(4)).  Once  decrypted,  the  user's  secret  key  is  stored  by 
the  local  key  server  process,  keyserv (1M).  This  stored  key  is  used  when  issuing  requests  to  any  secure  RPC 
services,  such  as  NIS+.  The  program  keylogout(l)  can  be  used  to  delete  the  key  stored  by  keyserv. 

keylogin  will  fail  if  it  cannot  get  the  caller's  key,  or  the  password  given  is  incorrect.  For  a  new  user  or 
host,  a  new  key  can  be  added  using  newkey(lM),  nisaddcred(lM),  or  nisei ient(llM). 

Options 

-r  Update  the  /etc/ .  rootkey  file.  This  file  holds  the  unencrypted  secret  key  of  the  super-user. 
Only  the  super-user  may  use  this  option.  It  is  used  so  that  processes  running  as  super-user  can  issue 
authenticated  requests  without  requiring  that  the  administrator  explicitly  run  keylogin  as  super- 
user  at  system  startup  time  (see  keyserv(lM)).  The  -r  option  should  be  used  by  the  administrator 
when  the  host's  entry  in  the  publickey  database  has  changed,  and  the  /etc/ .  rootkey  file  has 
become  out-of-date  with  respect  to  the  actual  key  pair  stored  in  the  publickey  database.  The  permis- 
sions on  the  /etc/  .  rootkey  file  are  such  that  it  may  be  read  and  written  by  the  super-user  but  by 
no  other  user  on  the  system. 

AUTHOR 

keylogin  was  developed  by  Sun  Microsystems,  Inc. 
FILES 

/etc/  .  rootkey  Super-user's  secret  key 
SEE  ALSO 

chkey(l),  keylogout(l),  login(l),  keyserv(lM),  newkey(lM),  nisaddcred(lM),  nisclient(lM),  publickey(4), 
nsswitch.conf(4). 
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NAME 

keylogout  -  delete  stored  secret  key  with  keyserv 

SYNOPSIS 

/usr/bin/keylogout  [  -f  ] 

DESCRIPTION 

keylogout  deletes  the  key  stored  by  the  key  server  process  keyserv(lM).  Further  access  to  the  key  is 
revoked;  however,  current  session  keys  may  remain  valid  until  they  expire  or  are  refreshed. 

Deleting  the  keys  stored  by  keyserv  will  cause  any  background  jobs  or  scheduled  at(l)  jobs  that  need 
secure  RPC  services  to  fail.  Since  only  one  copy  of  the  key  is  kept  on  a  machine,  it  is  a  bad  idea  to  place  a 
call  to  this  command  in  your  .  logout  file  since  it  will  affect  other  sessions  on  the  same  machine. 

Options 

-f    Force  keylogout  to  delete  the  secret  key  for  the  super-user.  By  default,  keylogout  by  the 
super-user  is  disallowed  because  it  would  break  all  RPC  services  that  are  started  by  the  super-user. 

AUTHOR 

keylogout  was  developed  by  Sun  Microsystems,  Inc. 
SEE  ALSO 

at(l),  chkey(l),  login(l),  keylogin(l),  keyserv(lM),  newkey(lM),  publickey(4). 
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NAME 

keysh  -  context-sensitive softkey  shell 

SYNOPSIS 

keysh 

DESCRIPTION 

keysh  is  an  extension  of  the  standard  Korn-shell  (for  a  description  of  the  basic  Korn-shell  functionality, 
see  ksh(l)). 

keysh  uses  hierarchical  softkey  menus  and  context-sensitive  help  to  aid  users  in  building  command-lines, 
combining  the  power  of  the  Korn-shell  with  theease-of-useof  a  menu  system. 

And  keysh  is  entirely  data-driven,  allowing  its  menus  and  help  to  be  easily  extended  as  needed. 

Note  that  during  keysh  invocation,  the  environment  variable  $TERM  must  specify  the  terminal  type,  as 
defined  in  theterminfo(4)  database  (see  environ  me  NT  variables  below). 

COMMAND  ENTRY 

keysh  continually  parses  the  command-line  and  always  presents  the  user  with  an  appropriate  set  of 
current  choices  on  the  softkey  labels. 

The  user  can  select  these  softkeys  to  create  readable  softkey  commands  on  the  command-line,  keysh 
automatically  translates  these  softkey  commands  into  equivalent  hp-ux  commands  prior  to  executing 
them. 

Alternatively,  the  user  can  ignore  the  softkeys  altogether  in  favor  of  entering  the  traditional  hp-ux  com- 
mands directly,  as  when  usingthe  Korn-shell. 

During  command  entry,  keysh  ordinarily  displays  a  status-line  near  the  bottom  of  the  screen.  This 
status-line  contains  information  such  as  the  host  name,  current  directory,  and  time  and  date. 

Whenever  the  user  must  perform  an  action  to  complete  the  current  softkey  command,  keysh  temporarily 
displays  a  prompt  message  in  pi  ace  of  the  status-line.  This  message  briefly  describes  the  required  action. 

Softkey  Types 

keysh  presents  four  basic  softkey  types: 

— Help —  Selecting  the  — Help —  softkey  causes  keysh  to  display  help  information  associ- 
ated with  the  next  selected  softkey,  rather  than  actually  performing  its  action. 

— More —  If  there  are  more  current  choices  than  there  are  softkeys,  keysh  breaks  the  choices 
into  banks  and  displays  a  special  — More —  softkey  along  with  the  first  bank. 
Selecting  the  — More —  softkey  causes  keysh  to  display  the  next  bank  of  softkeys 
in  sequence,  eventually  cycling  back  to  the  first. 

<param>  parameter  softkeys  are  displayed  as  a  name  enclosed  between  a  pair  of  less-than  and 
greater-than  symbols.  They  indicate  that  the  user-supplied  text  (such  as  a  file  name) 
should  be  entered  into  the  command-line  at  that  point,  rather  than  actually  selecting 
the  softkey.  (Actually  selecting  the  softkey  only  causes  keysh  to  display  a  hint  mes- 
sage on  the  status  line;  the  command-line  remains  unchanged.) 

option  All  other  softkeys  are  option  softkeys  that  can  be  used  to  insert  the  corresponding 
command  or  option  name  into  the  command-line. 

Softkeys  can  be  selected  from  left  to  right. 

Editing  The  Command-Line 

keysh  supports  the  normal  Korn-shell  command-line  editing  modes.  In  addition,  keysh  also  recognizes 
the  cursor  movement  and  editing  keys  found  on  most  terminals,  as  defined  in  the  terminfo(4)  database. 
These  include: 

<Clear  display>       Clear  the  screen  and  command-line.  If  the  screen  is  scrolled,  clear  only  from  the  cur- 
sor position  to  the  end  of  scrolling  memory. 

<Clear  line>  Clear  from  the  cursor  position  to  the  end  of  the  command-line. 

-delete  line>         Clear  the  entire  command-line. 
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<l  nsert  line> 


Translate  any  softkey  commands  in  the  current  command-line  and  then  edit  the 
result. 


-delete  char> 


Delete  the  character  under  the  cursor. 


<Ctrl-L> 


<l  nsert  char> 


<Up/Down  arrow> 
<L eft/Right  arrow> 
<Home  up/down > 
<Tab> 


<Backtab> 


Toggle  between  insert  and  overwrite  modes. 

Recall  the  previous/next  command  from  the  history  buffer. 

Move  the  cursor  left/right. 

Move  the  cursor  to  the  beginning/end  of  the  command-line. 

If  no  <l nsert  line>  key  is  present,  perform  the  <l nsert  line>  function  (see  above). 
Otherwise,  if  no  — Help —  softkey  is  present,  perform  the  — Help —  function 
(also  see  above).  Otherwise,  perform  the  normal  tab  function. 

Move  the  cursor  to  the  beginning  of  the  previous  word. 

Redraw  the  lower  lines  of  the  screen  and  restore  any  necessary  terminal  modes. 


Visible  Softkey  Commands 

If  the  visibles  configuration  option  is  enabled  (see  configuration  below),  keysh  displays  a  list  of 
configured  softkey  commands  on  the  softkey  labels  whenever  it  is  expecting  a  new  command.  This  is  the 
the  top-level  softkey  menu. 

If  the  user  selects  one  of  these  softkey  commands,  keysh  inserts  its  command  name  into  the  command- 
line  then  displays  a  sub-menu  listing  the  command's  major  parameters  and/or  options. 

The  user  can  then  (from  left  to  right)  select  option  softkeys  and/or  enter  text  in  pi  ace  of  parameter  softkeys. 
keysh  automatically  navigates  the  hierarchical  softkey  menu,  always  presenting  the  user  with  an 
appropriate  set  of  current  choices  on  the  softkey  labels. 

Note  that  keysh  automatically  redisplays  the  top-level  softkey  menu  when  it  detects  that  a  command 
separator  (such  as  a  pipe  or  semi-colon)  has  been  entered,  thus  allowing  the  user  to  use  softkeys  for  subse- 
quent commands  on  the  command-line  as  well  as  the  first. 

I  nvisible  Softkey  Commands 

If  the  invisibles  configuration  option  is  enabled  (see  configuration  below)  and  keysh  recognizes 
a  traditional  hp-ux  command  being  entered,  it  gives  the  user  one  last  chance  to  use  the  softkeys  by  again 
presenting  an  appropriate  set  of  current  choices  on  the  softkey  labels.  As  with  the  top-level  softkey  menu 
options,  the  user  can  choose  to  ignore  the  softkeys  in  favor  of  entering  the  traditional  hp-ux  options 
directly. 

Backup  Softkeys 

If  the  backups  configuration  option  is  enabled  (see  CON  figuration  below),  keysh  displays  the  backup 
softkeys  and  programs  the  terminal  function  keys  appropriately  whenever  it  has  no  other  softkeys  to 
display  (such  as  when  a  command  is  running).  These  provide  the  traditional  static  softkey  control  which 
many  users  may  be  used  to. 

Traditional  HP-UX  Commands 

If  the  user  enters  a  traditional  hp-ux  command  when  keysh  is  displaying  its  top-level  softkey  menu, 
keysh  simply  displays  the  backup  softkeys  and  allows  the  user  to  proceed. 

If  keysh  subsequently  detects  a  command  separator,  it  again  redisplays  the  top-level  softkey  menu. 

Softkey  Command  Syntax  E  rrors 

Many  softkey  commands  present  the  user  with  a  set  of  softkey  options  from  which  exactly  one  (or  at  least 
one)  must  be  selected.  If  the  user  fails  to  do  this,  keysh  treats  it  as  a  syntax  error,  displaying  an  error 
message  and  not  accepting  the  command  until  the  error  has  been  corrected. 

Similarly,  many  softkey  commands  require  that  the  user  enter  one  or  more  softkey  parameters  before  the 
command  is  semantical  ly  complete.  If  the  user  fails  to  do  this,  keysh  again  treats  it  as  a  syntax  error. 

Softkey  Command  Redirections 

The  user  can  append  redirection  symbols  (such  as  a  less-than  or  greater-than  symbol  followed  by  a  file 
name)  following  a  softkey  command.  These  are  appended  verbatim  to  the  translated  hp-ux  command. 
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USING  KEYSH  WITH  TERMINAL  SESSION  MANAGER 

When  operating  under  the  Terminal  Session  Manager  (see  tsm(l)):  keysh  displays  the  tsm  softkeys 
instead  of  the  backup  softkeys.  If  desired,  this  interaction  can  be  overridden  by  setting  the  $KEYTSM 
environment  variable(seeEiwiRONMENT  variables  below). 

When  operating  under  tsm,  keysh  also  automatically  displays  the  tsm  window  number  in  the  status- 
line. 

CONFIGURATION 

All  keysh  configuration  functions  are  accessed  through  the  top-level  Keysh_conf  ig  softkey  command 
or  kc  built-in  command.  These  functions  include: 

•  adding,  placing,  and  deleting  softkeys, 

•  specifying  backup  softkeys, 

•  selecting  global  options, 

•  selecting  status-line  items, 

•  restarting  keysh, 

•  writing  configuration  changes,  and 

•  undoing  other  configuration  changes. 

Each  time  the  user  changes  keysh's  configuration,  keysh  automatically  updates  the  user's 
$HOME/ .  keyshrc  file.  Upon  subsequent  invocations,  keysh  automatically  reconfigures  itself  as 
configured  previously. 

Adding,  Placing,  And  Deleting  Softkeys 

Any  of  the  standard  softkeys  (see  standard  softkey  definitions  below)  can  be  added  to  the  top-level 
softkey  menu  using  the  kc  softkey  add  command.  If  desired,  an  alternate  softkey  label  may  be 
specified  (usuallyin  place  of  a  crypticHP-ux  command  name)  usingthe  with_label  option. 

By  default,  added  softkeys  are  placed  at  the  end  of  the  last  — More —  bank  of  the  top-level  softkey  menu. 
This  placement  can  be  overridden  usingthe  and_place  option  of  the  kc  softkey  add  command  or 
usingthe  kc  softkey  move  command. 

I  n  addition  to  the  standard  softkeys,  custom  softkeys  can  also  be  added  from  custom  softkey  files  using  the 
from_user  or  from_file  options.  For  a  description  of  the  softkey  file  format,  see  softkeys(4). 

Note  that  any  time  a  softkey  is  added  from  a  particular  softkey  file,  all  of  the  remaining  softkeys  from  that 
file  are  automatically  loaded  for  use  as  invisible  softkey  commands.  All  softkeys  from  a  file  can  also  be 
loaded  for  useas  invisible  softkey  commands  usingthe  kc  softkey  add  invisibles  command. 

Any  of  the  softkeys  in  the  top-level  softkey  menu  can  be  deleted  using  the  kc  softkey  delete  com- 
mand. 

Specifying  Backup  Softkeys 

Backup  softkeys  are  typically  specified  in  the  user's  $HOME/  .  softkeys  file.  The  basic  backup  softkey 
definition  line  resembles: 

backup  softkey  "<softkey>"  literal  "<string>"; 

Where  <softkey>is  the  softkey  label  to  display  and  <string>is  the  text  string  to  program  the  terminal  func- 
tion key  with.  A  maximum  of  eight  backup  softkeys  can  be  specified. 

Note  that  backup  softkeys  must  be  explicitly  added  using  the  kc  softkey  add  backups  command 
before  keysh  can  program  them. 

Selecting  Global  Options 

Various  global  options  can  be  configured  usingthe  kc  option  command,  including: 

backups        Enableor  disablethe  programming  of  the  backup  softkeys. 

help  Enableor  disablethe  — Help — softkey. 

invisibles  Enableor  disablethe  recognition  of  invisible  softkey  commands. 

prompts  Enable  or  disable  the  automatic  generation  of  prompt  messages.  When  enabled, 
keysh  displays  a  prompt  message  whenever  the  user  must  perform  an  action  to  com- 
plete the  current  softkey  command.  This  message  briefly  describes  the  required 
action. 
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selectors  Enable  or  disablethe  use  of  keyboard  selectors.  When  enabled,  keysh  displays  an 
upper-case  selector  character  in  each  softkey  label.  Typing  the  unquoted  (upper-case) 
character  selects  the  softkey  just  as  if  its  corresponding  function  key  had  been 
pressed.  Quoting  the  selector  character  in  any  way  restores  its  traditional  meaning. 
Selector  keys  are  intended  to  be  used  on  terminals  that  do  not  support  a  sufficient 
number  of  softkeys. 

translations 

Enableor  disablethe  display  of  HP-UX  command  translations. 

visibles      Enableor  disablethe  presentation  and  recognition  of  visible  softkey  commands. 

Select i  ng  Status-L  i  ne  I  terns 

Various  information  items  can  be  configured  into  the  status-line  displayed  at  the  bottom  of  the  screen  using 
the  kc  status_line  command,  including: 

host_name    The  host  name. 

user_name    The  user  name. 

current_dir 

The  current  directory. 

mail_status 

The  mail  status  based  on  the  $MAIL  environment  variable  (i.e.,  No  mail,  You 
have  mail,  or  You  have  new  mail). 

date  The  date. 

time  The  time  of  day. 

I  n  addition,  the  $  KEYSH  environment  variable,  if  set,  is  always  displayed  first  in  the  status-line. 

Restarting  Keysh 

keysh  can  be  forced  to  reread  the  $HOME/  .  keyshrc  file  with  the  kc  restart  command.  This  com- 
mand is  typically  used  to  update  a  keysh  to  a  new  configuration  specified  in  another  window. 

keysh  can  also  be  forced  to  remove  the  $HOME/ .  keyshrc  file  and  restart  from  the  default  user 
configuration  with  the  kc  restart  default  command. 

Writing  Configuration  Changes 

keysh  can  be  forced  to  rewrite  the  $HOME/ .  keyshrc  file  with  the  kc  write  command. 

Undoing  Other  Configuration  Changes 

keysh  can  also  be  forced  to  rewrite  the  $HOME/  .  keyshrc  file  with  its  original  contents,  thus  undoing 
all  configuration  changes  made  si  nee  keysh  was  invoked,  using  the  kc  undo  command. 

Scaling  Keysh  Functionalities 

keysh  provides  a  scalableset  of  functionalities  which  can  be  tailored  to  suit  personal  preferences. 

For  users  who  are  familiar  with  the  hp-ux  command  names  (though  not  necessarily  with  the  command 
options)  or  for  users  who  prefer  to  usually  have  the  tsm  softkeys  visible,  the  command  kc  options 
visibles  off  prevents  keysh  from  displaying  its  top-level  softkey  menu  while  waiting  for  a  com- 
mand; instead,  it  displays  the  backup  softkeys  or  tsm  softkeys,  as  appropriate,  (keysh  start-up  time  can 
then  be  decreased  significantly  by  editing  the  $HOME/  .  keyshrc  file  and  removing  the  lines  which  add 
visible  softkeys.) 

For  users  who  are  also  familiar  with  the  HP-ux  command  options,  the  command  kc  options 
invisibles  off  prevents  keysh  from  displaying  softkey  menus  for  invisible  softkey  commands,  also. 

And  for  users  who  have  no  need  for  the  backup  softkeys,  the  command  kc  options  backups  off 
prevents  keysh  from  ever  programming  the  backup  softkeys. 

Note  that  if  visibles,  invisibles,  and  backups  are  all  turned  off,  keysh  performs  no  softkey 
processing  at  all.  keysh  effectively  transforms  into  a  Korn-shell  which  displays  a  status-line  and  recog- 
nizes the  cursor  movement  and  editing  keys. 
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EXAMPLES 

To  add  the  od  (see  od(l))  softkey  to  the  end  of  the  top-level  softkey  menu  and  label  it  Octal_dump , 

kc  softkey  add  od  with_label  Octal_dump 
To  add  the  paste(l)  softkey  to  the  beginning  of  the  top-level  softkey  menu  and  label  it  Paste, 

kc  softkey  add  paste  and__place  as_f irst_softkey 

To  add  the  custom  emacs  softkey  from  the  file  ~rpt/  .  softkeys  to  the  top-level  softkey  menu  immedi- 
ately before  the  Is  (see  I s(l))  softkey, 

kc  softkey  add  emacs  from_user  rpt  and__place  bef ore_softkey  Is 
To  add  all  invisible  softkeys  from  the  file  ~rpt/  .  softkeys, 

kc  softkey  add  invisibles   from_user  rpt 
To  add  the  backup  softkeys  from  the  file  $HOME/  .  softkeys, 

kc  softkey  add  backups 
To  delete  the  Edit_file  softkey  from  the  top-level  softkey  menu, 

kc  softkey  delete  Edit_file 
Todisablethe  — Help —  softkey, 

kc  options  help  off 
To  configure  the  user  name  into  the  status-line, 

kc  status_line  user_name  on 
To  configure  the  exit-value  of  the  last  command  executed  into  the  status-line, 

KEYSH="\${?#0} " 

To  list  the  ten  largest  files  in  the  current  directory, 

Is  long_format    |   Sort_lines  numerically  reverse_order  \ 
starting_at_f ield  5    |  head 

STANDARD  SOFTKEY  DEFINITIONS 

Copy_files,  Move_files,  Print_f iles  ,  Set_f ile_attribs,  Switch. 

adjust,  ar,  bdf,  cal,  cancel,  cat,  cd,  cdb,  chatr,  chgrp,  chmod,  chown,  cmp,  col,  comm, 
cpio,  cut,  dd,  df,  diff ,  dircmp,  disable, du,  elm,  enable,  exit,  find,  fold,  grep,  head, 
jobs,  kill,  lp,  lpstat,  Is,  mailx,  make,  man,  mkdir,  more,  nm,  nroff ,  od,  paste,  pg,  pr, 
ps,  remsh,  rlogin,  rm,  rmdir,  sdiff ,  set,  shar,  sort,  tail,  tar,  tee,  touch,  tr,  umask, 
uname,  vi,  wc,  who,  write,  xd,  xdb. 

ENVIRONMENT  VARIABLES 

TERM  Specifies  the  terminal  type,  as  defined  in  the  terminfo(4)  database.  This  variable  must  be 

either  part  of  keysh's  invocation  environment  or  it  must  beset  within  one  of  the  standard 
Korn-shell  start-up  files. 

COLUMNS       Specifies  the  number  of  columns  in  the  terminal  screen  if  different  than  the  terminfo(4) 
default. 

LINES  Specifies  the  number  of  lines  in  the  terminal  screen  if  not  the  same  as  the  terminfo(4) 

default. 

PAGER  Specifies  the  preferred  pager  to  be  used  to  display  help.  The  default  is  more  (see 

more(D). 

TZ  Specifies  the  time-zone  to  be  used  for  time  and  date  representations  on  the  status-line.  The 

default  is  en_US .  roman8  . 

KEYBEL         Specifies  the  character  sequence  sent  to  the  terminal  by  keysh  to  ring  the  bell.  The 
default  is  ~G. 

KEYENV         Specifies  an  alternate  keysh  configuration  file.  The  default  is  $HOME/  .  keyshrc. 

KEYESC         Specifies  the  maximum  allowable  delay  between  characters  (in  milliseconds)  if  they  are  to 
be  treated  as  part  of  a  terminal  escape  sequence.  The  default  is  350  ms. 
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KEYKSH 


If  set,  specifies  that  keysh  should  mimic  the  behavior  of  the  Korn-shell  as  closely  as  possi- 
ble. No  softkeys  or  status-line  are  displayed.  This  mode  is  particularly  useful  over  slow 
modem  lines. 


KEYLOC 


If  set,  specifies  that  keysh  should  leave  the  terminal  keypad  in  local  mode  while  com- 
mands are  being  entered.  This  mimics  the  behavior  of  the  Korn-shell. 


KEYPS1 


If  set,  specifies  that  keysh  should  not  reset  the  initial  values  of  $PS1,  $PS2,  and  $PS3. 
Note  that  $PS1  must  be  a  constant  character  string  in  order  for  keysh  to  recognize  it 
and  provide  subsequent  softkey  assistance. 


KEYSH 


Specifies  arbitrary  text  to  be  included  in  the  keysh  status-line. 


KEYSIM 


If  set,  specifies  that  keysh  should  always  simulate  softkey  labels  and  not  use  the  built-in 
label  son  hp  terminals. 


KEYTSM 


If  set,  specifies  that  keysh  should  not  use  the  tsm  softkeys  when  tsm  is  running.  In 
this  case,  the  user  can  either  use  the  tsm  hotkey,  the  backup  softkeys,  or  the  Switch 
softkey  command  (see standard  softkey  definitions  above)  to  switch  tsm  windows. 


KSH  DIFFERENCES 

keysh  is  an  extension  of  ksh(l)  with  the  foil  owing  exceptions: 

Screen  Updates 

keysh  optimizes  its  display  output  to  take  advantage  of  avail  able  terminal  capabilities.  Unlike  the  Korn- 
shell  which  often  has  to  redraw  large  portions  of  the  command-line,  keysh  can  simply  insert  or  delete 
characters  at  the  appropriate  screen  position. 

This  makes  keysh  significantly  faster  over  slow  modem  lines,  especially  if  the  $  KEYKSH  environment 
variableisset  (seeENViRONMENT  variables  above). 

E  macs-Mode  E  diting 

The  new  <ESC>v  command  performs  the  function  of  the  vi-mode  v  command. 

An  initial  ~N  command  recalls  the  history  line  following  the  history  line  executed  as  the  previous  com- 
mand. This  provides  an  easy  mechanism  to  repeat  a  sequence  of  history  commands. 

gmacs  editing  mode  is  not  supported;  emacs  editing  mode  follows  the  gnu  emacs  (18.54)  definition  of 
The  "@and  <ESC>n  ~K  commands  are  not  supported. 

TheM-<letter>and  M-]  <letter>  alias  functions  are  not  supported  (in  lieu  of  true  softkey  support). 
Vi -Mode  Editing 

The  new  o  command  performs  the  function  of  the  emacs-mode  ~0  command. 

An  initial  j  command  recalls  the  history  line  foil  owing  the  history  line  executed  as  the  previous  command. 
This  provides  an  easy  mechanism  to  repeat  a  sequence  of  history  commands. 

The  |  command  is  not  supported. 

The  (gKletter>  alias  function  is  not  supported  (in  lieu  of  true  softkey  support). 

The  u  command  performs  an  emacs-style  nested  undo;  u<space> performs  a  traditional  vi-style  undo. 
WARNINGS 

keysh  requires  that  the  $TERM  environment  variable  be  set  appropriately  in  your  $HOME/  .profile 
file.  It  also  requires  that  $LINES  and  $COLUMNS  be  set  appropriately  if  running  on  a  non-standard  size 
terminal.  Otherwise,  an  error  message  or  a  garbled  screen  display  results. 

keysh  requires  that  option  softkeys  be  selected  from  left  to  right.  When  editing  a  command-line,  it  is  pos- 
sibleto  back  up  and  insert  a  softkey  out-of-order  -  resulting  in  a  command  error. 

keysh  initializes  $PS1,  $PS2,  and  $PS3  and  types  them  read-only  —  do  not  change  them.  Instead,  use 
$  KEYSH  to  display  additional  status  information. 

keysh  normally  maintains  the  $HOME/ .  keyshrc  file  without  user  intervention;  however,  start-up 
errors  may  occasionally  occur  and  persist.  In  this  case,  either  execute  the  command  kc  restart 
default  (to  remove  the  file  and  revert  to  the  default  user  configuration)  or  execute  the  command  kc 
write  (to  rewrite  the  file  with  the  current  configuration). 
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keysh  assumes  that  HP-UX  commands  are  not  heavily  aliased;  otherwise  unexpected  command  transla- 
tions may  occur. 

keysh  neglects  the  effects  of  the  Korn-shell  expansion  mechanisms  when  counting  command-line  parame- 
ters, causing  it  to  occasionally  underestimate  the  true  number  of  parameters  specified.  The  <ESC>* 
emacs-mode  or  vi-mode  editing  command  can  often  be  used  to  pre-expand  these  parameters. 

The  <ESC>v  emacs-mode  editing  command  and  v  vi-mode  editing  command  cannot  be  used  to  edit  (pre- 
translated)  softkey  commands,  since  no  subsequent  command  translation  can  occur. 

Adding  a  large  number  of  softkeys  can  cause  keysh  to  overflow  a  1-Mbyte  Korn-shell  data  size  limitation, 
causing  disconcerting  behavior. 

keysh  can  only  program  the  function  keys  on  terminals  whose  terminfo(4)  entry  defines  the  pfkey  capa- 
bility; similarly,  it  can  only  use  hardware  softkey  labels  on  terminals  whose  terminfo(4)  entry  defines  the 
pin  capability  (along  with  specifying  lh  equal  to  2). 

The  default  value  for  $KEYESC  was  chosen  to  provide  reasonable  response  in  both  local  and  networked 
environments.  If  keysh  misinterprets  quickly  typed  emacs-mode  or  vi-mode  editing  commands  as  terminal 
escape  sequences,  it  may  be  necessary  to  decrease  this  value. 

Specifying  a  \n  (new-line)  in  the  literal  key  sequence  for  a  backup  softkey  causes  undesired  results  on  hp 
terminals;  usea  \r  (carriage-return)  instead. 

keysh  does  not  display  tsm  softkeys  when  simulatingsoftkey  labels. 

A  limited  number  of  environment  variables  and  arguments  are  exported  to  the  pager  when  displaying  help. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  softkeys  and  messages  are  displayed. 

LC_TIME  determines  the  format  and  contents  of  date  and  time  strings  in  the  status-line. 

I  nternational  Code  Set  Support 

Si  ngle-byte  character  code  sets  are  supported. 

AUTHOR 

keysh  was  developed  by  H  P  and  AT&T. 


FILES 


/usr/bin/keysh 

/usr/lib/keysh/builtins 

/usr/lib/keysh/$LANG/softkeys 

/usr/lib/keysh/$LANG/keyshrc 

/usr/lib/nls/$LANG/keysh . cat 

$HOME/ . keyshrc 

$HOME/ . softkeys 


main  executable 

Keysh_conf  ig  softkey  definition  file 
standard  softkey  definitions  file 
default  user  configuration  file 
message  catalog 
user  configuration  file 
user  softkey  definitions  file 


SEE  ALSO 

ksh(l),  tsm(l),  softkeys(4),  terminfo(4). 
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NAME 

kill  -  send  a  signal  to  a  process;  terminate  a  process 

SYNOPSIS 

kill  [-s  signame]  pid  ... 

kill  [-s  signum]  pid  ... 
kill  -1 

Obsolescent  Versions: 

kill  -signame  pid  ... 

kill  -signum  pid  ... 
DESCRIPTION 

The  kill  command  sends  a  signal  to  each  process  specified  by  a  pid  process  identifier.  The  default  signal 
is  SIGTERM,  which  normally  terminates  processes  that  do  not  trap  or  ignore  the  signal. 

pid  isa  process  identifier,  an  unsigned  or  negative  integer  that  can  be  one  of  the  following: 

>  0  The  number  of  a  process. 

=  0  All  processes,  except  special  system  processes,  whose  process  group  id  is  equal  to  the  process 
group  I D  of  the  sender. 

=-1  All  processes,  except  special  system  processes,  if  the  user  has  appropriate  privileges.  Otherwise, 
all  processes,  except  special  system  processes,  whose  real  or  effective  user  id  is  the  same  as  the 
user  I D  of  the  sendi  ng  process. 

<-l  All  processes,  except  special  system  processes,  whose  process  group  id  is  equal  to  the  absolute 
value  of  pid  and  whose  real  or  effective  user  id  is  the  same  as  the  user  of  the  sending  process. 

Process  numbers  can  be  found  with  the  ps  command  (see  ps(l))  and  with  the  built-in  jobs  command 
availablein  some  shells. 

Options 

kill  recognizes  the  following  options: 

-1      (ell)  List  all  values  of  signame  supported  by  the  implementation.  No  signals  are  sent 

with  this  option.  The  symbolic  names  of  the  signals  (without  the  SIG  prefix)  are 
written  to  standard  output,  separated  by  spaces  and  newlines. 

-s  signame  Send  the  specified  signal  name.  The  default  is  SIGTERM,  number  15.  signame 
can  be  specified  in  upper-  and/or  lowercase,  with  or  without  the  SIG  prefix.  These 
values  can  be  obtained  by  using  the  -1  option.  The  symbolic  name  SIGNULL 
represents  signal  value  zero.  See  "Signal  Names  and  Numbers"  below. 

-s  signum  Send  the  specified  decimal  signal  number.  The  default  is  15,  SIGTERM.  See"Sig- 

nal  Names  and  Numbers"  below. 

-signame  (Obsolescent.)  Equivalent  to -s  signame. 

-signum  (Obsolescent.)  Equivalent  to -s  signum. 


Signal  Names  and  Numbers 

The  following  table  describes  a  few  of  the  more  common  signals  that  can  be  useful  from  a  terminal.  For  a 
complete  list  and  a  full  description,  seethe  header  file  <signal  .h>  and  the  manual  entry  signal  (5). 


signum 

signame 

Name 

Description 

0 

SIGNULL 

Null 

Check  access  to  pid 

1 

SIGHUP 

Hangup 

Terminate;  can  be  trapped 

2 

SIGINT 

1  nterrupt 

Terminate;  can  be  trapped 

3 

SIGQUIT 

Quit 

Terminate  with  core  dump;  can  be  trapped 

9 

SIGKILL 

Kill 

Forced  termination;  cannot  be  trapped 

15 

SIGTERM 

Terminate 

Terminate;  can  be  trapped 
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24 
25 
26 


SIGSTOP     Stop  Pause  the  process;  cannot  be  trapped 

SIGTSTP     Terminal  stop    Pause  the  process;  can  be  trapped 
SIGCONT     Continue  Run  a  stopped  process 


SIGNULL  (0),  the  null  signal,  invokes  error  checking  but  no  signal  is  actually  sent.  This  can  be  used  to 
test  the  validity  or  existence  of  pid. 

SIGTERM  (15),  the  (default)  terminate  signal,  can  be  trapped  by  the  receiving  process,  allowing  the 
receiver  to  execute  an  orderly  shutdown  or  to  ignore  the  signal  entirely.  For  orderly  operations,  this  is  the 
perferred  choice. 

SIGKILL  (9),  the  kill  signal,  forces  a  process  to  terminate  immediately.  Since  SIGKILL  cannot  be 
trapped  or  ignored,  it  is  useful  for  terminating  a  process  that  does  not  respond  to  SIGTERM. 

The  receiving  process  must  belong  to  the  user  of  the  sending  process,  unless  the  user  has  appropriate 
privileges. 

As  a  single  special  case,  the  continue  signal  SIGCONT  can  be  sent  to  any  process  that  is  a  member  of  the 
same  session  as  the  sending  process. 

RETURN  VALUE 

Upon  completion,  kill  returns  with  one  of  the  foil  owing  values: 


0   At  least  one  matching  process  was  found  for  each  pid  operand,  and  the  specified  signal  was  suc- 
cessfully processed  for  at  least  one  matching  process. 

>0    An  error  occurred. 


EXAMPLES 

The  command: 

kill  6135 

signals  process  number  6135  to  terminate.  This  gives  the  process  an  opportunity  to  exit  gracefully  (remov- 
ing temporary  files,  etc.). 

Thefollowing  equivalent  commands: 

kill  -s  SIGKILL  6135 
kill  -s  KILL  6135 
kill  -s  9  6135 
kill  -SIGKILL  6135 
kill  -KILL  6135 
kill  -9  6135 

terminate  process  number  6135  abruptly  by  sending  a  SIGKILL  signal  to  the  process.  This  tells  the  ker- 
nel to  remove  the  process  immediately. 


If  a  process  hangs  during  some  operation  (such  as  I/O)  so  that  it  is  never  scheduled,  it  cannot  die  until  it  is 
allowed  to  run.  Thus,  such  a  process  may  never  go  away  after  the  kill.  Similarly,  defunct  processes  (see 
ps(l))  may  have  already  finished  executing,  but  remain  on  the  system  until  their  parent  reaps  them  (see 
wait(2)).  Using  kill  to  send  signalstothem  has  no  effect. 

Some  non-HP-ux  implementations  provide  kill  only  as  a  shell  built-in  command. 
DEPENDENCIES 

This  manual  entry  describes  the  external  command  /usr/bin/kill  and  the  built-in  kill  command  of 
the  POSIX  shell  (see  sh-posix(l)).  Other  shells,  such  as  C  and  Korn  (see  csh(l)  and  ksh(l)  respectively), 
also  provide  kill  as  a  built-in  command.  The  syntax  for  and  output  from  these  built-insmay  be  different. 

SEE  ALSO 

csh(l),  ksh(l),  ps(l),  sh(l),  sh-bourne(l),  sh-posix(l),  kill(2),  wait(2),  signal(5). 

STANDARDS  CONFORMANCE 

kill:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX. 2 


WARNINGS 
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NAME 

kinit  -  obtain  and  cachethe  Kerberos  ticket-granting  ticket 


SYNOPSIS 

kinit  [-1  lifetime]  [-s  start  time]  [-v]  [-p]  [-f]  [-k  [-t  keytabfilename]]  [-r  renewablelife] 
[-R]  [-c  cachefilename]  [-S  service-name]  [principal] 

DESCRIPTION 

kinit  obtains  and  caches  an  initial  ticket-granting  ticket  for  the  principal . 
Options 

-1  life  time  Requests  a  ticket  with  the  lifetime  value  defined  in  life  time.  The  value  for  life  time 

must  be  followed  immediately  by  one  of  the  following  delimiters: 

s  seconds 
m  minutes 
h  hours 
d  days 

For  example,  as  in  kinit  -1  90m  for  90  minutes.  You  cannot  mix  units;  a  value  of 
3h30m  will  result  in  an  error. 

If  the  -1  option  is  not  specified,  the  default  ticket  lifetime  (configured  by  each  site)  is 
used.  Specifying  a  ticket  lifetime  longer  than  the  maximum  ticket  lifetime  (configured 
by  each  site)  results  in  a  ticket  with  the  maximum  lifetime. 

-s  start  time  Requests  a  postdated  ticket,  valid  starting  at  start  time.  The  format  for  start  time  is 
the  same  as  the  -1  option,  one  of  the  following:  seconds,  minutes,  hours,  or  days. 
Postdated  tickets  are  issued  with  the  invalid  flag  set,  and  need  to  be  fed  back  to  the 
Kerberos  KDC  (Key  Distribution  Center)  before  use. 

-v  Requests  that  the  ticket  granting  ticket  in  the  cache  (with  the  invalid  flag  set)  be 

passed  to  the  KDC  for  validation.  If  the  ticket  is  within  its  requested  time  range,  the 
cache  is  replaced  with  the  validated  ticket. 

-p  Requests  proxiabletickets. 

-f  Requests  forwardabletickets. 

-r  renewable  life  Requests  renewable  tickets,  with  a  total  lifetime  of  renewable  life.  The  format  for 
renewable  life  is  the  same  as  the  -1  option,  one  of  the  following:  seconds,  minutes, 
hours,  or  days. 

-R  Requests  renewal  of  the  ticket-granting  ticket.  Note  that  an  expired  ticket  cannot  be 

renewed,  even  if  the  ticket  isstill  within  its  renewablelife. 

-k  [-t  keytab  filename] 

Requests  a  host  ticket,  obtained  from  a  key  in  the  local  host's  keytab  file.  The  name 
and  location  of  the  keytab  file  may  be  specified  with  the  -t  keytab  filename  option; 
otherwise  the  default  nameand  location  will  be  used. 

-c  cachefilename  Uses cache  filenameasthecredentialsticket  cachenameand  location.  Ifthisoption  is 
not  used,  the  default  cache  nameand  location  are  used. 

The  default  credentials  cache  may  vary  between  systems.  If  the  KRB5CCNAME 
environment  variable  is  set,  its  value  is  used  to  name  the  default  ticket  cache.  Any 
existi  ng  contents  of  the  cache  are  destroyed  by  kinit . 

-S  servicename     Specifies  an  alternate  service  name  to  use  when  getting  initial  tickets. 

principal  Uses  the  principal  name  from  an  existing  cache  if  there  is  one. 


Note 

For  DCE  operations  use  /opt/dce/bin/kinit. 

Environment 

kinit  uses  the  foil  owing  environment  variable: 

KRB5CCNAME         Location  of  the  credentials  ticket  cache. 
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FILES 

/tmp/krb5cc_{uid}  Default  credentials  cache.  {uid}is  the  decimal  Ul  D  of  the  user. 
/etc/krb5  .  keytab    Default  location  for  the  local  host's  keytab  file. 

AUTHOR 

kinit  was  developed  by  the  Massachusetts  I  nstitute  of  Technology. 

SEE  ALSO 

kdestroy(l),  kerberos(9),  klist(l),  Iibkrb5(3). 
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NAME 

klist  -  list  cached  Kerberos  tickets 
SYNOPSIS 

klist  [-e]  [[-c]  [-f]  [-s]  [cachefilename]]  [-k  [-t]  [-K]  [ke/tab_filename]] 
DESCRIPTION 

klist  lists  the  Kerberos  principal  and  Kerberos  tickets  held  in  a  credentials  cache,  or  the  keys  held  in  a 
keytab  file. 

Options 

-e  Displays  the  encryption  types  of  the  session  key  and  the  ticket  for  each  credential  in  the  creden- 

tial cache,  or  each  key  in  the  keytab  file. 

-c  List  tickets  held  in  a  credentials  cache.  This  is  the  default  if  neither  -c  nor  -k  is  specified. 

-f  Shows  the  flags  present  in  the  credentials,  usingthe  following  abbreviations: 


F 

Forwardable 

f 

forwarded 

P 

Proxiable 

P 

proxy 

D 

postdateable 

d 

postdated 

R 

Renewable 

I 

1  nitial 

i 

invalid 

-s  Causes  klist  to  run  silently  (produce  no  output),  but  still  sets  the  exit  status  depending  on 

whether  it  finds  the  credentials  cache.  The  exit  status  is  '0'  if  klist  finds  a  credentials  cache, 
and  the  exit  status  is  T  if  it  does  not. 

-k  List  keys  held  in  a  keytab  file. 

-t  Display  the  time  entry  timestamps  for  each  keytab  entry  in  the  keytab  file. 

-K  Display  the  value  of  the  encryption  key  of  the  keytab  entry  in  the  keytab  file. 

If  cache  filename  or  keytabfilename  is  not  specified,  klist  will  display  the  credentials  in  the  default 
credentials  cache  or  keytab  file  as  appropriate.  If  the  KRB5CCNAME  environment  variable  is  set,  its  value 
is  used  to  name  the  default  ticket  cache. 

Note 

For  DCE  operations  use  /opt/dce/bin/klist. 

Environment 

klist  uses  the  foil  owing  environment  variable: 

KRB5CCNAME  Location  of  the  credentials  (ticket)  cache. 
FILES 

/tmp/krb5cc_{uid}     Default  credentials  cache.  {uid}is  the  decimal  U I D  of  the  user. 
/etc/krb5  .  keytab    Default  location  of  the  keytab  file. 

AUTHOR 

klist  was  developed  by  the  Massachusetts  I  nstitute  of  Technology. 

SEE  ALSO 

kdestroy(l),  kerberos(9),  kinit(l). 
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NAME 

kpasswd  -  change  a  user's  Kerberos  password 

SYNOPSIS 

kpasswd  [principal] 

DESCRIPTION 

The  kpasswd  command  is  used  to  change  a  Kerberos  principal's  password,  kpasswd  prompts  for  the 
current  Kerberos  password,  which  is  used  to  obtain  a  changepw  ticket  from  the  KDC  (Key  Distribution 
Center)  for  the  user's  Kerberos  realm.  If  kpasswd  successfully  obtains  the  changepw  ticket,  the  user  is 
prompted  twice  for  the  new  password,  and  the  password  is  changed. 

If  the  principal  is  governed  by  a  policy  that  specifies  the  length  and/or  number  of  character  classes  required 
in  the  new  password,  the  new  password  must  conform  to  the  policy.  The  five  character  classes  are  lower 
case,  upper  case,  numbers,  punctuation,  and  all  other  characters. 

Options 

principal  Changes  the  password  for  the  Kerberos  principal,  principal,  kpasswd  uses  the  principal 
name  from  an  existing  cache  if  there  is  one.  If  not,  the  principal  is  derived  from  the  identity 
of  the  user  invoking  the  kpasswd  command. 

Note 

kpasswd  looks  first  for  kpasswd_server  =  host  :port  in  the  [realms]  section  of  the  krb5  .  conf 
file  under  the  current  realm.  If  that  is  missing,  kpasswd  looks  for  the  adminserver  entry,  and  substi- 
tutes 464  for  the  port. 

FILES 

/etc/krb5  .  conf        Kerberos  configuration  file. 
AUTHOR 

kpasswd  was  developed  by  the  Massachusetts  I  nstitute  of  Technology. 

SEE  ALSO 

kerberos(9),  krb5.conf(4). 
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NAME 

ksh,  rksh  -  shell,  the  standard/restricted  command  programming  language 
SYNOPSIS 

ksh  [-aef hikmnoprstuvx]  [+aef hikmnoprstuvx]  [-o  option]  ...  [+o  option]  ...  [-c 
string]  [arg  ...] 

rksh  [-aef hikmnoprstuvx]  [+aef hikmnoprstuvx]  [-o  option]  ...  [+o  option]  ...  [-c 
string]  [arg  ...] 

DESCRIPTION 

ksh  is  a  command  programming  language  that  executes  commands  read  from  a  terminal  or  a  file,  rksh 
is  a  restricted  version  of  the  command  interpreter  ksh,  used  to  set  up  login  names  and  execution  environ- 
ments whose  capabilities  are  more  controlled  than  those  of  the  standard  shell.  See  Invoking  ksh  and  Spe- 
cial Commands  sections  later  in  this  entry  for  details  about  command  line  options  and  arguments,  particu- 
larly the  set  command. 

Definitions 
metacharacter 

One  of  the  following  characters: 

;       &       (      )       |       <      >  new-line  space  tab 
A  tab  or  space  character. 

A  sequence  of  letters,  digits,  or  underscores  starting  with  a  letter  or  underscore.  Identifiers 
are  used  as  names  for  functions  and  named  parameters. 

A  sequence  of  characters  separated  by  one  or  more  non-quoted  metacharacters  . 

A  sequence  of  characters  in  the  syntax  of  the  shell  language.  The  shell  reads  each  com- 
mand and  carries  out  the  desired  action,  either  directly  or  by  invoking  separate  utilities. 

special  command 

A  command  that  is  carried  out  by  the  shell  without  creating  a  separate  process.  Often 
called  "built-in  commands".  Except  for  documented  side  effects,  most  special  commands 
can  be  i mpl emented  as  separate  utilities. 

#  The  #  character  is  interpreted  as  the  beginning  of  a  comment.  See  Quoting  below. 

Commands 

A  simple-command  is  a  sequence  of  blank-separated  words  that  can  be  preceded  by  a  parameter  assign- 
ment list.  (See  Environment  below).  The  first  word  specifies  the  name  of  the  command  to  be  executed. 
Except  as  specified  below,  the  remaining  words  are  passed  as  arguments  to  the  invoked  command.  The 
command  name  is  passed  as  argument  0  (see  exec(2)).  The  value  of  a  simple-command  is  its  exit  status  if 
it  terminates  normally,  or  (octal)  200-istatus  if  it  terminates  abnormally  (see  signal (5)  for  a  list  of  status 
values). 

A  pipeline  is  a  sequence  of  one  or  more  commands  separated  by  | .  The  standard  output  of  each  com- 
mand except  the  last  is  connected  by  a  pipe  (see  pipe(2))  to  the  standard  input  of  the  next  command.  Each 
command  is  run  as  a  separate  process;  the  shell  waits  for  the  last  command  to  terminate.  The  exit  status 
of  a  pipeline  is  the  exit  status  of  the  last  command  in  the  pipeline. 

A  list  is  a  sequence  of  one  or  more  pipelines  separated  by  ; ,  &,  &&,  or  |  | ,  and  optionally  terminated  by  ; , 
&,  or  |  &.  Of  these  five  symbols,  ; ,  &,  and  |  &  have  equal  precedence.  &&  and  |  |  have  a  higher  but  also 
equal  precedence.  A  semicolon  (; )  causes  sequential  execution  of  the  preceding  pipeline;  an  ampersand  (&) 
causes  asynchronous  execution  of  the  preceding  pipeline  (that  is,  the  shell  does  not  wait  for  that  pipelineto 
finish).  The  symbol  |  &  causes  asynchronous  execution  of  the  preceding  command  or  pipeline  with  a  two- 
way  pipe  established  to  the  parent  shell  (known  as  a  co-process).  The  standard  input  and  output  of  the 
spawned  command  can  be  written  to  and  read  from  by  the  parent  shell  using  the  -p  option  of  the  special 
commands  read  and  print  described  later.  Thesymbol  &&(  |  | )  causes  the  list  following  it  to  be  exe- 
cuted only  if  the  preceding  pipeline  returns  a  zero  (non-zero)  value.  An  arbitrary  number  of  new-lines  can 
appear  in  a  list,  instead  of  semicolons,  to  delimit  commands. 

A  command  is  either  a  simple-command  or  one  of  the  following.  Unless  otherwise  stated,  the  value 
returned  by  a  command  is  that  of  the  last  simple-command  executed  in  the  command. 


blank 
identifier 

word 
command 
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for  identifier  [in  word...]  do  list  done 

Each  time  for  is  executed,  identifier  is  set  to  the  next  word  taken  from  the  in  word  list. 
If  in  word  ...  is  omitted,  for  executes  the  do  list  once  for  each  positional  parameter  set 
(see  Parameter  Substitution  below).  Execution  ends  when  there  are  no  more  words  in  the 
list. 

select  identifier  [in  word...]  do  list  done 

A  select  command  prints  on  standard  error  (file  descriptor  2),  the  set  of  words,  each 
preceded  by  a  number.  If  in  word  ...  is  omitted,  the  positional  parameters  are  used 
instead  (see  Parameter  Substitution  below).  The  PS3  prompt  is  printed  and  a  line  is  read 
from  the  standard  input.  If  this  line  starts  with  the  number  of  one  of  the  listed  words,  the 
value  of  the  parameter  identifier  is  set  to  the  word  corresponding  to  this  number.  If  this 
line  is  empty,  the  selection  list  is  printed  again.  Otherwise  the  value  of  the  parameter 
identifier  is  set  to  null.  The  contents  of  the  line  read  from  standard  input  is  saved  in  the 
parameter  REPLY.  The  list  is  executed  for  each  selection  until  a  break  or  end-of-file 
(eof)  is  encountered. 

case  word  in  [  [    ( ]  pattern  [    |  pattern  ]  ...   )  list  ; ;    ]  ...  esac 

A  case  command  executes  the  list  associated  with  the  first  pattern  that  matches  word. 
The  form  of  the  patterns  is  identical  to  that  used  for  file  name  generation  (see  File  Name 
Generation  below). 

if  list  then  list  [  elif  list  then  list]  ...  [  else  list]  fi 

The  list  following  if  is  executed  and,  if  it  returns  a  zero  exit  status,  the  list  following  the 
first  then  is  executed.  Otherwise,  the  list  following  elif  is  executed  and,  if  its  value  is 
zero,  the  list  following  the  next  then  is  executed.  Failing  that,  the  else  list  is  executed. 
If  no  else  list  or  then  list  is  executed,  if  returns  a  zero  exit  status. 

while  list  do  list  done 

until  list  do  list  done 

A  while  command  repeatedly  executes  the  while  list,  and  if  the  exit  status  of  the  last 
command  in  the  list  is  zero,  executes  the  do  list;  otherwise  the  loop  terminates.  If  no 
commands  in  the  do  list  are  executed,  while  returns  a  zero  exit  status;  until  can  be 
used  in  pi  ace  of  while  to  negate  the  loop  termination  test. 

( list )  Execute  list  in  a  separate  environment.  If  two  adjacent  open  parentheses  are  needed  for 

nesting,  a  space  must  be  inserted  to  avoid  arithmetic  evaluation  as  described  below. 

{  list;}  Execute  list,  but  not  in  a  separate  environment.  Note  that  {  is  a  keyword  and  requires  a 
trailing  blank  to  be  recognized. 

[  [  expression  ]  ] 

Evaluates  expression  and  returns  a  zero  exit  status  when  expression  is  true.  See  Condi- 
tional Expressions  below,  for  a  description  of  expression.  Note  that  [  [  and  ]  ]  are  key- 
words and  require  blanks  between  them  and  expression. 

function  identifier  {list;} 
identifier   ()  {list;} 

Define  a  function  referred  to  by  identifier.  The  body  of  the  function  is  the  list  of  commands 

between  {and  }  (see  Functions  below). 

time  pipeline  pipeline  is  executed  and  the  elapsed  time,  user  time,  and  system  time  are  printed  on  stan- 
dard error.  Note  that  the  time  keyword  can  appear  anywhere  in  the  pipeline  to  time  the 
entire  pipeline  To  time  a  particular  command  in  a  pipeline,  see  time(l). 

Thefollowing  keywords  are  recognized  only  as  the  first  word  of  a  command  and  when  not  quoted: 

if  then  else  elif  fi  case  esac  for  while 
until  do  done   {    }  function  select  time    [ [   ] ] 

Comments 

A  word  beginning  with  #  causes  that  word  and  all  subsequent  characters  up  to  a  new-line  to  be  ignored. 
Aliasing 

The  first  word  of  each  command  is  replaced  by  the  text  of  an  alias,  if  an  alias  for  this  word  has  been 
defined.  An  alias  name  consists  of  any  number  of  characters  excluding  metacharacters,  quoting  charac- 
ters, file  expansion  characters,  parameter  and  command  substitution  characters,  and  =.  The  replacement 
string  can  contain  any  valid  shell  script,  including  the  metacharacters  listed  above.  The  first  word  of  each 
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command  in  the  replaced  text,  other  than  any  that  are  in  the  process  of  being  replaced,  is  tested  for  addi- 
tional aliases.  If  the  last  character  of  the  alias  value  is  a  blank,  the  word  following  the  alias  is  also  checked 
for  alias  substitution.  Aliases  can  be  used  to  redefine  special  built-in  commands,  but  cannot  be  used  to 
redefine  the  keywords  listed  above.  Aliases  can  be  created,  listed,  and  exported  with  the  alias  command 
and  can  be  removed  with  the  unalias  command.  Exported  aliases  remain  in  effect  for  subshells  but 
must  be  reinitialized  for  separate  invocations  of  the  shell  (see  I  nvoking  ksh  below). 

Aliasing  is  performed  when  scripts  are  read,  not  while  they  are  executed.  Therefore,  for  it  to  take  effect, 
alias  must  be  executed  before  the  command  referring  to  the  alias  is  read. 

Aliases  are  frequently  used  asa  shorthand  for  full  path  names.  An  option  to  the  aliasing  facility  allows  the 
value  of  the  alias  to  be  automatically  set  to  the  full  path  name  of  the  corresponding  command.  These 
aliases  are  called  tracked  aliases.  The  value  of  a  tracked  alias  is  defined  the  first  time  the  identifier  is 
read  and  becomes  undefined  each  time  the  PATH  variable  is  reset.  These  aliases  remain  tracked  so  that 
the  next  reference  redefines  the  value.  Several  tracked  aliases  are  compiled  into  the  shell.  The  -h  option 
of  the  set  command  converts  each  command  name  that  is  an  identifier  into  a  tracked  alias. 

Thefollowing  exported  aliases  are  compiled  into  the  shell  but  can  be  unset  or  redefined: 

autoload=' typeset  -fu' 
false='let  0' 
functions=' typeset  -f 
hash=' alias  -t  -' 
history=' fc  -1' 
integer= ' typeset  -i ' 
nohup= ' nohup  ' 
r='fc  -e  -' 
stop='kill  -STOP ' 
suspend='kill   -STOP  $$' 
true='  :  ' 

type= ' whence  -v' 
Tilde  Substitution 

After  alias  substitution  is  performed,  each  word  is  checked  to  see  if  it  begins  with  an  unquoted  ~.  If  it  does, 
the  word  up  to  a  /  is  checked  to  see  if  it  matches  a  user  name  in  the  /etc/passwd  file.  If  a  match  is 
found,  the  ~  and  the  matched  login  name  are  replaced  by  the  login  directory  of  the  matched  user.  This  is 
called  a  tilde  substitution.  If  no  match  is  found,  the  original  text  is  left  unchanged.  A  ",  alone  or  before  a 
/,  is  replaced  by  the  value  of  the  HOME  parameter.  A  ~  followed  by  a  +  or  -  is  replaced  by  the  value  of 
the  parameter  PWD  and  OLDPWD,  respectively.  In  addition,  tilde  substitution  isattempted  when  the  value 
of  a  parameter  assignment  begins  with  a  ~. 

Command  Substitution 

The  standard  output  from  a  command  enclosed  in  parenthesis  preceded  by  a  dollar  sign  ($  (command)  ) 
or  a  pair  of  back  single  quotes  (accent  grave)  ( v  command"  )  can  be  used  as  part  or  all  of  a  word;  trailing 
new-lines  are  removed.  I  n  the  second  (archaic)  form,  the  string  between  the  quotes  is  processed  for  special 
quoting  characters  before  the  command  is  executed  (see  Quoting  below).  The  command  substitution 
$(cat  file)  can  be  replaced  by  the  equivalent  but  faster  $  (<file)  .  Command  substitution  of  most 
special  commands  (built-ins)  that  do  not  perform  I/O  redirection  are  carried  out  without  creating  a  separate 
process.  However,  command  substitution  of  a  function  creates  a  separate  process  to  execute  the  function 
and  all  commands  (built-in  or  otherwise)  in  that  function. 

An  arithmetic  expression  enclosed  in  double  parenthesis  preceded  by  a  dollar  sign  ($  ( (expression) ) )  is 
replaced  by  the  value  of  the  arithmetic  expression  within  the  double  parenthesis  (see  Arithmetic  Evaluation 
below  for  a  description  of  arithmetic  expressions). 

Parameter  Substitution 

A  parameter  is  an  identifier,  one  or  more  digits,  or  any  of  the  characters  *,  @,  #,  ?,  -,  $,  and  ! .  A 
named  parameter  (a  parameter  denoted  by  an  identifier)  has  a  value  and  zero  or  more  attributes.  Named 
parameters  can  be  assigned  values  and  attributes  by  using  the  typeset  special  command.  Attributes 
supported  by  ksh  are  described  later  with  the  typeset  special  command.  Exported  parameters  pass 
val  ues  and  attri  butes  to  the  envi  ronment. 

The  shell  supports  a  limited  one-dimensional  array  facility.  An  element  of  an  array  parameter  is  refer- 
enced by  a  subscript.  A  subscript  is  denoted  by  a  [  followed  by  an  arithmetic  expression  (see  Arithmetic 
Evaluation  below)  followed  by  a  ] .  To  assign  values  to  an  array,  use  set  -A  name  value  ... .  Thevalue 
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of  all  subscripts  must  be  in  the  rangeof  0  through  1023.  Arrays  need  not  be  declared.  Any  reference  to  a 
named  parameter  with  a  valid  subscript  is  legal  and  an  array  is  created  if  necessary.  Referencing  an  array 
without  a  subscript  is  equivalent  to  referencing  the  first  element. 

The  value  of  a  named  parameter  can  also  be  assigned  by  writing: 

name=value  [name=value]  ... 

If  the  -i  integer  attribute  is  set  for  name,  the  value  is  subject  to  arithmetic  evaluation  as  described  below. 

Positional  parameters,  parameters  denoted  by  a  number,  can  be  assigned  values  with  the  set  special  com- 
mand. Parameter  $0  is  set  from  argument  zero  when  the  shell  is  invoked. 

Thecharacter  $  is  used  to  introduce substitutable  parameters. 

${parameter}  Substitute  the  value  of  the  parameter,  if  any.  Braces  are  required  when  param- 
eter is  followed  by  a  letter,  digit,  or  underscore  that  should  not  be  interpreted  as 
part  of  its  name  or  when  a  named  parameter  is  subscripted.  If  parameter  is  one 
or  more  digits,  it  is  a  positional  parameter.  A  positional  parameter  of  more  than 
one  digit  must  be  enclosed  in  braces.  If  parameter  is  *  or  @  all  the  positional 
parameters,  starting  with  $1,  are  substituted  (separated  by  a  field  separator 
character).  If  an  array  identifier  with  subscript  *  or  @  is  used,  the  value  for 
each  element  is  substituted  (separated  by  a  field  separator  character).  The  shell 
reads  all  the  characters  from  ${  to  the  matching  }  as  part  of  the  same  word 
even  if  it  contains  braces  or  metacharacters. 

${#parameter }  If  parameter  is  *  or  @,  the  number  of  positional  parameters  is  substituted. 
Otherwise,  thelength  of  the  value  of  the  parameter  is  substituted. 

${#identifier  [*] }   Substitute  the  number  of  elements  in  the  array  identifier. 

$  { parameter  :  -word  } 

If  parameter  is  set  and  is  non-null,  substitute  its  value;  otherwise  substitute 
word. 

$  { parameter  :  =word  } 

If  parameter  is  not  set  or  is  null,  set  it  to  word;  then  substitute  the  value  of  the 
parameter.  Positional  parameters  cannot  be  assigned  in  this  way. 

$  { parameter  :  ?  word  } 

If  parameter  is  set  and  is  non-null,  substitute  its  value;  otherwise,  print  word 
and  exit  from  the  shell.  If  word  is  omitted,  a  standard  message  is  printed. 

$  { parameter  :  +word  } 

If  parameter  is  set  and  is  non-null,  substitute  word;  otherwise  substitute  noth- 
ing. 

$  { pa  ra  meter  #  pattern  } 

${parameter##pattern } 

If  the  shell  pattern  matches  the  beginning  of  the  value  of  parameter,  the  value  of 
this  substitution  is  the  value  of  the  parameter  with  the  matched  portion  deleted; 
otherwise  the  value  of  this  parameter  substituted.  I  n  the  former  case,  the  smal- 
lest matching  pattern  is  deleted;  in  the  latter  case,  the  largest  matching  pattern 
is  deleted. 

$  { pa  ra  meter  %  pattern  } 

$ { pa  ra  meter  %  %  pattern  } 

If  the  shell  pattern  matches  the  end  of  the  value  of  parameter,  the  value  of 
parameter  with  the  matched  part  is  deleted;  otherwise  substitute  the  value  of 
parameter.  In  the  former,  the  smallest  matching  pattern  is  deleted;  in  the 
latter,  the  largest  matching  pattern  is  deleted. 

I  n  the  above,  word  is  not  evaluated  unless  it  is  used  as  the  substituted  string.  Thus,  in  the  following 
example,  pwd  is  executed  only  if  d  is  not  set  or  is  null: 

echo  ${d:-$(pwd)} 

If  the  colon  ( : )  is  omitted  from  the  above  expressions,  the  shell  only  checks  to  determine  whether  or 
not  parameter  is  set. 
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Thefollowing  parameters  are  set  automatically  by  the  shell: 


i 


COLUMNS 


ERRNO 

LINENO 
LINES 


OLDPWD 

OPTARG 

OPTIND 

PPID 

PWD 

RANDOM 


REPLY 
SECONDS 


The  number  of  positional  parameters  in  decimal. 

Options  supplied  to  the  shell  on  invocation  or  by  the  set  command. 

Thedecimal  value  returned  by  the  last  executed  command. 

The  process  number  of  this  shell. 

I  nitially,  the  value  of  _  is  an  absolute  pathname  of  the  shell  or  script  being  executed 
as  passed  in  the  environment.  Subsequently  it  is  assigned  the  last  argument  of  the 
previous  command.  This  parameter  is  not  set  for  commands  which  are  asynchronous. 
This  parameter  is  also  used  to  hold  the  name  of  the  matching  MAIL  file  when  check- 
i  ng  for  mai  I . 

The  process  number  of  the  last  background  command  invoked. 
If  this  variable  is  set,  its  value  is  used  to  define  the  width  of  the  edit  window  for  the 
shell  edit  modes  and  for  printing  select  lists.  In  a  windowed  environment,  if  the 
shell  detects  that  the  window  size  has  changed,  the  shell  updates  the  value  of 

COLUMNS . 

Thevalueof  errno  as  set  by  the  most  recently  failed  system  call.  This  value  is  sys- 
tem dependent  and  is  intended  for  debugging  purposes. 

The  line  number  of  the  current  line  within  the  script  or  function  being  executed. 

If  this  variable  is  set,  the  value  is  used  to  determine  the  column  length  for  printing 

select  lists,    select  lists  print  vertically  until  about  two-thirds  of  LINES  lines 

are  filled.  In  a  windowed  environment,  if  the  shell  detects  that  the  window  size  has 

changed,  the  shel  I  updates  the  val  ue  of  LINES . 

The  previous  working  directory  set  by  the  cd  command. 

The  value  of  the  last  option  argument  processed  by  the  getopts  special  command. 
The  index  of  the  last  option  argument  processed  by  the  getopts  special  command. 
The  process  number  of  the  parent  of  the  shell. 
The  present  working  directory  set  by  the  cd  command. 

Each  time  this  parameter  is  evaluated,  a  random  integer,  uniformly  distributed 
between  0  and  32767,  is  generated.  The  sequence  of  random  numbers  can  be  initial- 
ized by  assigninga  numeric  value  to  RANDOM. 

This  parameter  is  set  by  the  select  statement  and  by  the  read  special  command 
when  no  arguments  are  supplied. 

Each  time  this  parameter  is  referenced,  the  number  of  seconds  since  shell  invocation 
is  returned.  If  this  parameter  is  assigned  a  value,  the  value  returned  upon  reference 
is  the  value  that  was  assigned  plus  the  number  of  seconds  si  nee  the  assignment. 


Thefollowing  parameters  are  used  by  the  shell: 


CDPATH 
EDITOR 


ENV 


FCEDIT 
FPATH 


IFS 


HISTFILE 


HISTSIZE 


HOME 


The  search  path  for  the  cd  command. 

If  thevalueof  this  variableends  in  emacs,  gmacs,  or  vi  and  the  VISUAL  variable 
is  not  set,  the  corresponding  option  is  turned  on  (see  set  in  Special  Commands 
below). 

If  this  parameter  is  set,  parameter  substitution  is  performed  on  the  value  to  generate 
the  path  name  of  the  script  to  be  executed  when  the  shell  is  invoked  (see  I  nvoking  ksh 
below).  This  file  is  typically  used  for  alias  and  function  definitions. 
The  default  editor  name  for  the  fc  command. 

The  search  path  for  function  definitions.  This  path  is  searched  when  a  function  with 
the  -u  attribute  is  referenced  and  when  a  command  is  not  found.  If  an  executable 
file  is  found,  then  it  is  read  and  executed  in  the  current  environment. 
Internal  field  separators,  normally  space,  tab,  and  new-linethat  are  used  to  separate 
command  words  resulting  from  command  or  parameter  substitution,  and  for  separat- 
ing words  with  the  special  command  read.  The  first  character  of  the  IFS  parame- 
ter is  used  to  separate  arguments  for  the  "$*"  substitution  (see  Quoting  below). 
If  this  parameter  is  set  when  the  shell  is  invoked,  its  value  is  the  path  name  of  the  file 
that    is    used    to    store    the    command    history.     The    default    value  is 
$HOME/  .  sh_history.  If  the  user  has  appropriate  privileges  and  no  HISTFILE 
is  given,  then  no  history  file  is  used  (see  Command  Re-entry  below). 
If  this  parameter  is  set  when  the  shell  is  invoked,  the  number  of  previously  entered 
commands  accessible  to  this  shell  will  be  greater  than  or  equal  to  this  number.  The 
default  is  128. 

The  default  argument  (home  di  rectory)  for  the  cd  command. 
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MAIL  If  this  parameter  is  set  to  the  name  of  a  mail  file  and  the  MAILPATH  parameter  is 

not  set,  the  shell  informs  the  user  of  arrival  of  mail  in  the  specified  file. 

MAILCHECK  This  variable  specifies  how  often  (in  seconds)  the  shell  checks  for  changes  in  the 
modification  time  of  any  of  the  files  specified  by  the  MAILPATH  or  MAIL  parame- 
ters. The  default  value  is  600  seconds.  When  the  time  has  elapsed  the  shell  checks 
before  issuingthe  next  prompt. 

MAILPATH  A  list  of  file  names  separated  by  colons  (:).  If  this  parameter  is  set,  the  shell  informs 
the  user  of  any  modifications  to  the  specified  files  that  have  occurred  within  the  last 
MAILCHECK  seconds.  Each  file  name  can  be  followed  by  a  ?  and  a  message  to  be 
printed,  in  which  case  the  message  undergoes  parameter  and  command  substitution 
with  the  parameter  $_  defined  as  the  name  of  the  changed  file.  The  default  message 
is  you  have  mail  in  $_. 

PATH  The  search  path  for  commands  (see  Execution  below).  The  user  cannot  change  PATH 

if  executing  rksh  (except  i  n  the  .profile  file). 

PS1  The  value  of  this  parameter  is  expanded  for  parameter  substitution,  to  define  the  pri- 

mary prompt  string  which,  by  default,  is  $  followed  by  a  space  character.  The  char- 
acter !  in  the  primary  prompt  string  is  replaced  by  the  command  number  (see  Com- 
mand Re-entry  below).  Toincludea  !  in  the  prompt,  use  !! . 

PS2  Secondary  prompt  string,  by  default  >  followed  by  a  space  character. 

PS3  Selection  prompt  string  used  within  a  select  loop,  by  default  #?  followed  by  a 

space  character. 

PS4  The  value  of  this  variable  is  expanded  for  parameter  substitution  and  precedes  each 

line  of  an  execution  trace.  If  PS4  is  unset,  the  execution  trace  prompt  is  +  followed 
by  a  space  character. 

SHELL  The  path  name  of  the  shell  is  kept  in  the  environment.  When  invoked,  the  shell  is 

restricted  if  the  value  of  this  variable  contains  an  r  in  the  basename. 

TMOUT  If  set  to  a  value  greater  than  zero,  the  shell  terminates  if  a  command  is  not  entered 

within  the  prescribed  number  of  seconds  after  issuingthe  PS1  prompt. 

VISUAL  Invokes  the  corresponding  option  when  the  value  of  this  variable  ends  in  emacs, 
gmacs,  or  vi  (see  set  in  Special  Commands  below). 

The  shell  gives  default  values  to  PATH,  PS1,  PS2,  MAILCHECK,  TMOUT,  and  IFS.  HOME,  SHELL,  ENV, 
and  MAIL  are  never  set  automatically  by  the  shell  (although  HOME,  SHELL,  and  MAIL  are  set  by 
login(l)). 


Blank  Interpretation 

After  parameter  and  command  substitution,  the  results  of  substitution  are  scanned  for  field  separator  char- 
acters (found  in  IFS),  and  split  into  distinct  arguments  where  such  characters  are  found,  ksh  retains 
explicit  null  arguments  (  or  '  ' )  but  removes  implicit  null  arguments  (those  resulting  from  parameters  that 
have  no  values). 

File  Name  Generation 

Following  substitution,  each  command  word  is  processed  as  a  pattern  for  file  name  expansion  unless  the 
-f  option  has  been  set.  The  form  of  the  patterns  is  the  Pattern  Matching  Notation  defined  by  regexp(5). 
The  word  is  replaced  with  sorted  file  names  matching  the  pattern.  If  no  file  name  is  found  that  matches 
the  pattern,  the  word  is  left  unchanged. 

In  addition  to  the  notation  described  in  regexp(5),  ksh  recognizes  composite  patterns  made  up  of  one  or 
more  pattern  lists  separated  from  each  other  with  a  | .  Composite  patterns  can  be  formed  with  one  or  more 
of  the  following: 

?  (pattern-list)        Optionally  matches  any  one  of  the  given  patterns. 

*  (pattern-list)        Matches  zero  or  more  occurrences  of  the  given  patterns. 

+  (pattern-list)        Matches  one  or  more  occurrences  of  the  given  patterns. 

@  (pattern-list)        Matches  exactly  one  of  the  given  patterns. 

!  (pattern-list)        Matches  anything,  except  one  of  the  given  patterns. 

Quoting 

Each  of  the  metacharacters  listed  above  (See  Definitions  above)  has  a  special  meaning  to  the  shell  and 
causes  termination  of  a  word  unless  quoted.  A  character  can  be  quoted  (i.e.,  made  to  stand  for  itself)  by 
preceding  it  with  a  \.  The  pair  \new-lineis  ignored.  All  characters  enclosed  between  a  pair  of  single  quote 
marks  ('  ' ),  are  quoted.  A  single  quote  cannot  appear  within  single  quotes.  Inside  double  quote  marks 
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(" "),  parameter  and  command  substitution  occurs  and  \  quotes  the  characters  \,  v ,  ",  and  $.  $*  and 
$@  have  identical  meanings  when  not  quoted  or  when  used  as  a  parameter  assignment  value  or  as  a  file 
name.  However,  when  used  as  a  command  argument,  "$*"  is  equivalent  to  "$id  $2d where  d  is  the 
first  character  of  the  IFS  parameter,  whereas  "$@"  is  equivalent  to  "$2"  ....  I  nside  back  single 

quote  (accent  grave)  marks  C  " )  \  quotes  the  characters  \,  v ,  and  $.  If  the  back  single  quotes  occur 
within  double  quotes,  \  also  quotes  the  character  ". 

The  special  meaning  of  keywords  or  aliases  can  be  removed  by  quoting  any  character  of  the  keyword.  The 
recognition  of  function  names  or  special  command  names  listed  below  cannot  be  altered  by  quoting  them. 

Arithmetic  Evaluation 

The  ability  to  perform  integer  arithmetic  is  provided  with  the  special  command  let.  Evaluations  are  per- 
formed using  long  arithmetic.  Constants  take  the  form  [base#]n,  where  base  is  a  decimal  number  between 
two  and  thirty-six  representing  the  arithmetic  baseand  n  is  a  number  in  that  base.  If  base  is  omitted,  base 
10  is  used. 

An  arithmetic  expression  uses  the  same  syntax,  precedence,  and  associativity  of  expression  of  the  C 
language.  All  the  integral  operators,  other  than ++, — ,  ?:,and  ,  are  supported.  Variables  can  be  refer- 
enced by  name  within  an  arithmetic  expression  without  using  the  parameter  substitution  syntax.  When  a 
variable  is  referenced,  its  value  is  evaluated  as  an  arithmetic  expression. 

An  internal  integer  representation  of  a  variablecan  be  specified  with  the  -i  option  of  the  typeset  spe- 
cial command.  Arithmetic  evaluation  is  performed  on  the  value  of  each  assignment  to  a  variable  with  the 
-i  attribute.  If  you  do  not  specify  an  arithmetic  base,  the  first  assignment  to  the  variable  determines  the 
arithmetic  base.  This  base  is  used  when  parameter  substitution  occurs. 

Since  many  of  the  arithmetic  operators  require  quoting,  an  alternative  form  of  the  let  command  is  pro- 
vided. For  any  command  beginning  with  ((,  all  characters  until  the  matching  ))  are  treated  as  a  quoted 
expression.  More  precisely,  ((...))  is  equivalent  to  let 

Prompting 

When  used  interactively,  the  shell  prompts  with  the  value  of  PS1  before  reading  a  command.  If  at  any 
time  a  new-line  is  typed  and  further  input  is  needed  to  complete  a  command,  the  secondary  prompt  (the 
value  of  PS2)  isissued. 

Conditional  Expressions. 
A  conditional  expression  is  used  with  the  [  [  compound  command  to  test  attributes  of  files  and  to  com- 
parestrings.  Word  splitting  and  file  name  generation  are  not  performed  on  the  words  between  [[  and]]. 
Each  expression  can  be  constructed  from  one  or  more  of  the  foil  owing  unary  or  binary  expressions: 


-a 

file 

True  if  fileexists. 

-b 

file 

True  if  fileexists  and  isa  block  special  file. 

-c 

file 

True  if  fileexists  and  isa  character  special  file. 

-d 

file 

True  if  fileexists  and  isa  directory. 

-f 

file 

True  if  fileexists  and  isan  ordinary  file. 

-g 

file 

True  if  fileexists  and  is  has  its  setgid  bit  set. 

-h 

file 

True  if  fileexists  and  isa  a  symbolic  link. 

-k 

file 

True  if  fileexists  and  is  has  its  sticky  bit  set. 

-n 

string 

True  if  length  of  string  is  non-zero. 

-o 

option 

True  if  option  named  option  is  on. 

-P 

file 

True  if  fileexists  and  isa  fifo  special  file  or  a  pipe. 

-r 

file 

True  if  fileexists  and  is  readableby  current  process. 

-s 

file 

True  if  fileexists  and  has  size  greater  than  zero. 

-t 

fildes 

True  if  file  descriptor  number  fildes  is  open  and  associated  with  a  terminal  dev- 
ice. 

-u 

file 

True  if  fileexists  and  is  has  its  setuid  bit  set. 

-w 

file 

True  if  fileexists  and  is  writable  by  current  process. 

-x 

file 

True  if  file  exists  and  is  executable  by  current  process.  If  file  exists  and  is  a 

directory,  the  current  process  has  permission  to  search  in  the  directory. 

-z 

string 

Trueif  length  of  string  iszero.  -L  fileTrue  if  fileexists  and  isa  symbolic  link. 

-0 

file 

True  if  fileexists  and  is  owned  by  the  effective  user  id  of  this  process. 

-G 

file 

True  if  fileexists  and  its  group  matches  the  effective  groupm  of  this  process. 

-S 

file 

True  if  fileexists  and  isa  socket. 

filel  -nt  file2 

True  if  filel  exists  and  is  newer  than  file2. 
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filel  -ot  file2 
filel  -ef  file2 
string  =  pattern 
string  !=  pattern 
stringl  <  string2 
stringl  >  string2 
expl  -eq  exp2 
expl  -ne  exp2 
expl  -It  exp2 
expl  -gt  exp2 
expl  -le  exp2 
expl  -ge  exp2 


True  if  filel  exists  and  is  older  than  file2. 

True  if  filel  and  file2  exist  and  refer  to  the  same  file. 

True  if  string  matches  pattern. 

True  if  string  does  not  match  pattern. 

True  if  stringl  comes  before  string2  based  on  ASCII  value  of  their  characters. 

True  if  stringl  comes  after  string2  based  on  ASCII  value  of  their  characters. 

True  if  expl  is  equal  to  exp2. 

True  if  expl  is  not  equal  to  exp2. 

True  if  expl  is  less  than  exp2. 

True  if  expl  is  greater  than  exp2. 

True  if  expl  is  less  than  or  equal  toexp2. 

True  if  expl  is  greater  than  or  equal  to  exp2. 


A  compound  expression  can  be  constructed  from  these  primitives  by  using  any  of  the  following,  listed  in 
decreasi  ng  order  of  precedence. 


(expression) 
!  expression 

expressionl  &&  expression 2 

expression!   |  |  expression 2 


True,  if  expression  is  true.  Used  to  group  expressions. 
True  if  expression  is  false. 
True,  if  expressionl  and  expression2  are  both  true. 
True,  if  either  expressionl  or  expression2  is  true. 


Input/Output 

Before  a  command  is  executed,  its  input  and  output  can  be  redirected  using  a  special  notation  interpreted 
by  the  shell.  Thefollowing  can  appear  anywhere  in  a  simple-command  or  can  precede  or  follow  a  command 
and  are  not  passed  on  to  the  invoked  command.  Command  and  parameter  substitution  occurs  before  word 
or  digit  is  used,  except  as  noted  below.  File  name  generation  occurs  only  if  the  pattern  matches  a  single  file 
and  blank  interpretation  is  not  performed. 

<word  Usefileword  as  standard  input  (file  descriptor  0). 

>word  Use  file  word  as  standard  output  (file  descriptor  1).  If  the  file  does  not  exist,  it  is 

created.  If  the  file  exists,  and  the  noclobber  option  is  on,  an  error  occurs;  other- 
wise, the  file  is  truncated  to  zero  length. 

>  |  word  Sames  as  >,  except  that  it  overrides  the  noclobber  option. 

»word  Usefileword  as  standard  output.  If  the  file  exists,  output  is  appended  to  it  (by  first 

searching  for  the  end-of-file);  otherwise,  the  file  is  created. 

oword  Open  file  word  for  reading  and  writing  as  standard  input.  If  the  file  does  not  exist  it 

is  created. 

«[-]word  The  shell  input  is  read  up  to  a  line  that  matches  word,  or  to  an  end-of-file.  No  param- 
eter substitution,  command  substitution,  or  file  name  generation  is  performed  on 
word.  The  resulting  document,  called  a  here-document,  becomes  the  standard 
input.  If  any  character  of  word  is  quoted,  no  interpretation  is  placed  upon  the  charac- 
ters of  the  document.  Otherwise,  parameter  and  command  substitution  occurs, 
\new-line  is  ignored,  and  \  must  be  used  to  quote  the  characters  \,  $,  v ,  and  the 
first  character  of  word.  If  -  is  appended  to  «,  all  leading  tabs  are  stripped  from 
word  and  from  the  document. 

<&digit  The  standard  input  is  duplicated  from  file  descriptor  digit  (see  dup(2)). 

>&digit  The  standard  output  is  duplicated  to  file  descriptor  digit  (seedup(2)). 

<&-  Thestandard  input  isclosed. 

>&-  The  standard  output  isclosed. 

<&p  The  input  from  the  co-process  is  moved  to  standard  input. 

>&p  The  output  to  the  co-process  is  moved  to  standard  output. 

If  one  of  the  above  is  preceded  by  a  digit,  the  file  descriptor  number  cited  is  that  specified  by  the  digit 
(instead  of  the  default  0  or  1).  For  example: 

...  2>&1 

means  file  descriptor  2  is  to  be  opened  for  writing  as  a  duplicate  of  file  descriptor  1. 
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Redirection  order  is  significant  because  the  shell  evaluates  redirections  referencing  file  descriptors  in  terms 
of  the  currently  open  file  associated  with  the  specified  file  descriptor  at  the  time  of  evaluation.  For  exam- 
ple: 

...   i>fname  2>si 

first  assigns  file  descriptor  1  (standard  output)  to  file  fname ,  then  assigns  file  descriptor  2  (standard  error) 
to  the  file  assigned  to  file  descriptor  1;  i.e.,  fname.  On  the  other  hand,  if  the  order  of  redirection  is  reversed 
as  follows: 

...   2>si  i>fname 

file  descriptor  2  is  assigned  to  the  current  standard  output  (user  terminal  unless  a  different  assignment  is 
inherited).  File  descriptor  1  is  then  reassigned  to  file  fname  without  changing  the  assignment  of  file 
descriptor  2. 

The  input  and  output  of  a  co-process  can  be  moved  to  a  numbered  file  descriptor  allowing  other  commands 
to  write  to  them  and  read  from  them  using  the  above  redirection  operators.  If  the  input  of  the  current  co- 
process  is  moved  to  a  numbered  file  descriptor,  another  co-process  can  be  started. 

If  a  command  is  followed  by  &  and  job  control  is  inactive,  the  default  standard  input  for  the  command  is 
the  empty  file  /dev/null .  Otherwise,  the  environment  for  the  execution  of  a  command  contains  the  file 
descriptors  of  the  invoking  shell  as  modified  by  input/output  specifications. 

Environment 

The  environment  (see  environ  (5))  is  a  list  of  name-value  pairs  passed  to  an  executed  program  much  like  a 
normal  argument  list.  The  names  must  be  identifiers  and  the  values  are  character  strings.  The  shell 
interacts  with  the  environment  in  several  ways.  When  invoked,  the  shell  scans  the  environment  and 
creates  a  parameter  for  each  name  found,  gives  it  the  corresponding  value,  and  marks  it  export.  Executed 
commands  inherit  the  environment.  If  the  user  modifies  the  values  of  these  parameters  or  creates  new 
ones  by  using  the  export  or  typeset  -x  commands,  the  values  become  part  of  the  environment.  The 
environment  seen  by  any  executed  command  is  thus  composed  of  any  name-value  pairs  originally  inherited 
by  the  shell  whose  values  can  be  modified  by  the  current  shell,  plus  any  additions  which  must  be  noted  in 
export  or  typeset  -x  commands. 

The  environment  for  any  simple-command  or  function  can  be  augmented  by  prefixing  it  with  one  or  more 
parameter  assignments.  A  parameter  assignment  argument  takes  the  form  identifier=value.  For  example, 

TERM=450  cmd  args 

and 

(export  TERM;   TERM=450;  cmd  args) 

are  equivalent  (as  far  as  the  above  execution  of  cmd  is  concerned  except  for  special  commands  listed  below 
that  are  preceded  by  a  percent  sign). 

If  the  -k  option  is  set,  all  parameter  assignment  arguments  are  placed  in  the  environment,  even  if  they 
occur  after  the  command  name.  The  following  echo  statement  prints  a=b  c.  After  the  -k  option  is  set, 
the  second  echo  statement  prints  only  c: 

echo  a=b  c 
set  -k 
echo  a=b  c 

This  feature  is  intended  for  use  with  scripts  written  for  early  versions  of  the  shell,  and  its  use  in  new 
scripts  is  strongly  discouraged.  It  is  likely  to  disappear  someday. 

Functions 

The  function  keyword  (described  in  the  Commands  section  above)  is  used  to  define  shell  functions. 
Shell  functions  are  read  and  stored  internally.  Alias  names  are  resolved  when  the  function  is  read.  Func- 
tions are  executed  like  commands,  with  the  arguments  passed  as  positional  parameters  (see  Execution 
below). 

Functions  execute  in  the  same  process  as  the  caller  except  that  command  substitution  of  a  function  creates 
a  new  process.  Functions  share  all  files  and  present  working  directory  with  the  caller.  Traps  caught  by  the 
caller  are  reset  to  their  default  action  inside  the  function.  If  a  function  does  not  catch  or  specifically  ignore 
a  trap  condition,  the  function  terminates  and  the  condition  is  passed  on  to  the  caller.  A  trap  on  EXIT  set 
inside  a  function  is  executed  after  the  function  completes  in  the  environment  of  the  caller.  Ordinarily,  vari- 
ables are  shared  between  the  calling  program  and  the  function.  However,  the  typeset  special  command 
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used  within  a  function  defines  local  variables  whose  scope  includes  the  current  function  and  all  functions  it 
calls. 

The  special  command  return  is  used  to  return  from  function  calls.  Errors  within  functions  return  con- 
trol to  the  caller. 

Function  identifiers  can  be  listed  with  the  +f  option  of  the  typeset  special  command.  Function 
identifiers  and  the  associated  text  of  the  functions  can  be  listed  with  the  -f  option.  Functions  can  be 
undefined  with  the  -f  option  of  the  unset  special  command. 

Ordinarily,  functions  are  unset  when  the  shell  executes  a  shell  script.  The  -xf  option  of  the  typeset 
command  allows  a  function  to  be  exported  to  scripts  that  are  executed  without  reinvoking  the  shell.  Func- 
tions that  must  be  defined  across  separate  invocations  of  the  shell  should  be  placed  in  the  ENV  file. 

J  obs 

If  the  monitor  option  of  the  set  command  is  turned  on,  an  interactive  shell  associates  a  job  with  each 
pipeline.  It  keeps  a  table  of  current  jobs,  printed  by  the  jobs  command,  and  assigns  them  small  integer 
numbers.  When  a  job  is  started  asynchronously  with  &,  the  shell  prints  a  line  resembling: 

[1]  1234 

indicating  that  job  number  1  was  started  asynchronously  and  had  one  (top-level)  process  whose  process  id 
was  1234. 

If  you  are  running  a  job  and  want  to  do  something  else,  type  the  suspend  character  (usually  "Z  (Ctrl-Z))  to 
send  a  stop  signal  to  the  current  job.  The  shell  then  indicates  that  the  job  has  been  'Stopped',  and  prints 
another  prompt.  The  state  of  this  job  can  be  manipulated  by  using  the  bg  command  to  put  it  in  the  back- 
ground, running  other  commands  (while  it  is  stopped  or  running  in  the  background),  and  eventually  res- 
tarting or  returning  the  job  to  the  foreground  by  using  the  fg  command.  A  *Z  takes  effect  immediately 
and  resembles  an  interrupt,  since  pending  output  and  unread  input  are  discarded  when  "Z  is  typed. 

A  job  run  in  the  background  stops  if  it  tries  to  read  from  the  terminal.  Background  jobs  normally  are 
allowed  to  produce  output,  but  can  be  disabled  by  giving  the  stty  tostop  command.  If  the  user  sets 
this  tty  option,  background  jobs  stop  when  trying  to  produce  output. 

There  are  several  ways  to  refer  to  jobs  in  the  shell.  A  job  can  be  referred  to  by  the  process  id  of  any  process 
in  the  job  or  by  one  of  the  following: 


%number  Thejob  with  the  given  number. 

%string  Any  job  whose  command  line  begins  with  string. 

%?string  Any  job  whose  command  line  contains  string. 

%%  Current  job. 

%+  Equivalent  to  %%. 

%-  Previous  job. 


The  shell  learns  immediately  when  a  process  changes  state.  It  informs  the  user  when  a  job  is  blocked  and 
prevented  from  further  progress,  but  only  just  before  it  prints  a  prompt. 

When  the  monitor  mode  is  on,  each  background  job  that  completes  triggers  any  trap  set  for  CHLD. 

Attempting  to  leave  the  shell  while  jobs  are  running  or  stopped  produces  the  warning,  You  have 
stopped  (running)  jobs.  Use  the  jobs  command  to  identify  them.  An  immediate  attempt  to 
exit  again  terminates  the  stopped  jobs;  the  shell  does  not  produce  a  warning  the  second  time. 

Signals 

The  int  and  quit  signals  for  an  invoked  command  are  ignored  if  the  command  is  followed  by  &  and  the 
monitor  option  is  off.  Otherwise,  signals  have  the  values  inherited  by  the  shell  from  its  parent,  with  the 
exception  of  signal  11  (but  see  also  the  trap  command  below). 

Execution 

Substitutions  are  made  each  time  a  command  is  executed.  If  the  command  name  matches  one  of  the  Spe- 
cial Commands  listed  below,  it  is  executed  within  the  current  shell  process.  Next,  ksh  checks  the  com- 
mand name  to  determine  whether  it  matches  one  of  the  user-defined  functions.  If  it  does,  ksh  saves  the 
positional  parameters  and  then  sets  them  to  the  arguments  of  the  function  call.  The  positional  parameter 
0  is  set  to  the  function  name.  When  the  function  completes  or  issues  a  return,  ksh  restores  the  posi- 
tional parameter  list  and  executes  any  trap  set  on  EXIT  within  the  function.  The  value  of  a  function  is  the 
value  of  the  last  command  executed.  A  function  is  executed  in  the  current  shell  process.  If  a  command 
name  is  not  a  special  command  or  a  user-defined  function,  ksh  creates  a  process  and  attempts  to 
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execute  the  command  using  exec  (see  exec(2)). 

The  shel  I  parameter  PATH  defines  the  search  path  for  the  di  rectory  contai  ni  ng  the  command.  Alternative 
directory  names  are  separated  by  a  colon  (:).  The  default  path  is  /usr/bin:  (specifying  /usr/bin 
and  the  current  directory  in  that  order).  Note  that  the  current  directory  is  specified  by  a  null  path  name 
which  can  appear  immediately  after  the  equals  sign,  between  colon  delimiters,  or  at  the  end  of  the  path  list. 
The  search  path  is  not  used  if  the  command  name  contains  a  /.  Otherwise,  each  directory  in  the  path  is 
searched  for  an  executable  file.  If  the  file  has  execute  permissions  but  is  not  a  directory  or  an  executable 
object  code  file,  it  is  assumed  to  be  a  script  file,  which  is  a  file  of  data  for  an  interpreter.  If  the  first  two 
characters  of  the  script  file  are  #! ,  exec  (see  exec(2))  expects  an  interpreter  path  name  to  follow,  exec 
then  attempts  to  execute  the  specified  interpreter  as  a  separate  process  to  read  the  entire  script  file.  If  a 
call  to  exec  fails,  /usr/bin/ksh  is  spawned  to  interpret  the  script  file.  All  non-exported  aliases,  func- 
tions, and  named  parameters  are  removed  in  this  case.  If  the  shell  command  file  does  not  have  read  per- 
mission, or  if  the  setuid  and/or  setgid  bits  are  set  on  the  file,  the  shell  executes  an  agent  to  set  up  the  per- 
missions and  execute  the  shell  with  the  shell  command  file  passed  down  as  an  open  file.  A  parenthesized 
command  is  also  executed  in  a  sub-shell  without  removing  non-exported  quantities. 

Command  Re-entry 

The  text  of  the  last  HISTSIZE  (default  128)  commands  entered  from  a  terminal  device  is  saved  in  a  his- 
tory file.  The  file  $HOME/  .  sh_history  is  used  if  the  HISTFILE  variable  is  not  set  or  writable.  A 
shell  can  access  the  commands  of  all  interactive  shel  Is  that  use  the  same  named  HISTFILE .  The  special 
command  f  c  is  used  to  list  or  edit  a  portion  of  this  file.  The  portion  of  the  file  to  be  edited  or  listed  can  be 
selected  by  number  or  by  giving  the  first  character  or  characters  of  the  command.  A  single  command  or 
range  of  commands  can  be  specified.  If  no  editor  program  is  specified  as  an  argument  to  f  c,  the  value  of 
the  FCEDIT  parameter  is  used.  If  FCEDIT  is  not  defined,  /usr/bin/ed  is  used.  The  edited  com- 
mand is  printed  and  re-executed  upon  leaving  the  editor.  The  editor  name  -  is  used  to  skip  the  editing 
phase  and  to  re-execute  the  command.  In  this  case  a  substitution  parameter  of  the  form  old=new  can  be 
used  to  modify  the  command  before  execution.  For  example,  if  r  is  aliased  to  fc  -e  -,  typing  r 
bad=good  c  re-executes  the  most  recent  command  that  starts  with  the  letter  c  and  replaces  the  first 
occurrence  of  the  string  bad  with  the  string  good. 

The  hi  story  file  will  be  trimmed  when  all  of  the  foil  owing  conditions  occurs: 

Its  size  is  greater  than  four  kilobytes. 

The  number  of  commands  in  it  is  more  than  HISTSIZE . 

Thefile  has  not  been  modified  in  the  last  ten  minutes. 

The  user  has  write  permission  for  the  directory  in  which  the  history  file  resides. 

If  any  one  of  the  above  conditions  does  not  occur,  the  history  file  will  not  be  trimmed.  When  the  history  file 
istrimmed,  the  latest  HISTSIZE  commands  will  beavailablein  the  history  file. 

Special  Commands 

The  following  simple-commands  are  executed  in  the  shell  process.  They  permit  input/output  redirection. 
Unless  otherwise  indicated,  file  descriptor  1  is  the  default  output  location  and  the  exit  status,  when  there 
are  no  syntax  errors,  iszero.  Commands  that  are  preceded  by  %  or  %%  are  treated  specially  in  the  follow- 
ing ways: 

1.  Variable  assignment  lists  preceding  the  command  remain  in  effect  when  the  command  completes. 

2.  I/O  redirections  are  processed  after  variableassignments. 

3.  E  rrors  cause  a  scri  pt  that  contai  ns  them  to  abort. 

4.  Words  following  a  command  preceded  by  %%  that  are  in  the  format  of  a  variable  assignment  are 
expanded  with  the  same  rules  as  a  variable  assignment.  This  means  that  tilde  substitution  is  per- 
formed after  the  =  sign  and  word  splitting  and  file  name  generation  are  not  performed. 

%  :  [arg  ...]   The  command  only  expands  parameters.  A  zero  exit  code  is  returned. 

%  .  fi le [arg  ...] 

Read  and  execute  commands  from  file  and  return.  The  commands  are  executed  in  the 
current  shell  environment.  Thesearch  path  specified  by  PATH  is  used  to  find  the  directory 
containing  file.  If  any  arguments  arg  are  given,  they  become  the  positional  parameters. 
Otherwise  the  positional  parameters  are  unchanged.  The  exit  status  is  the  exit  status  of 
the  last  command  executed.  It  is  not  necessary  that  the  execute  permission  bit  be  set  for 
file. 
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%%  alias  [-tx]  [name[=value]  ...] 

alias  with  no  arguments  prints  the  list  of  aliases  in  the  form  name=value  on  standard 
output.  An  alias  is  defined  for  each  name  whose  value  is  given.  A  trailing  space  in  value 
causes  the  next  word  to  be  checked  for  alias  substitution.  The  -t  option  is  used  to  set  and 
list  tracked  aliases.  The  value  of  a  tracked  alias  is  the  full  path  name  corresponding  to  the 
given  name.  The  value  of  a  tracked  alias  becomes  undefined  when  the  value  of  PATH  is 
reset,  but  the  alias  remains  tracked.  Without  the  -t  option,  for  each  name  in  the  argu- 
ment list  for  which  no  value  is  given,  the  name  and  value  of  the  alias  is  printed.  The  -x 
option  is  used  to  set  or  print  exported  aliases.  An  exported  alias  is  defined  across  sub-shell 
environments.  Alias  returns  true  unless  a  name  is  given  for  which  no  alias  has  been 
defined. 

bg  [job...]  Puts  the  specified  jobs  into  the  background.  The  current  job  is  put  in  the  background  if  job 
is  unspecified.  SeeJ  obsfor  a  description  of  the  format  of  job. 

%  break  [n]  Exit  from  the  enclosing  for,  while,  until,  or  select  loop,  if  any.  If  n  is  specified, 
break  n  levels. 

%  continue  [n] 

Resume  the  next  iteration  of  the  enclosing  for,  while,  until,  or  select  loop.  Ifnis 
specified,  resume  at  the  n-th  enclosing  loop. 

cd  [-L|-P][arg] 

cd  old  new  This  command  can  take  either  of  two  forms.  I  n  the  first  form  it  changes  the  current  direc- 
tory toarg.  Ifargis  -  the  directory  is  changed  to  the  previous  directory.  The  -L  option 
(default)  preserves  logical  naming  when  treating  symbolic  links,  cd  -L  ..  moves  the 
current  directory  one  path  component  closer  to  the  root  directory.  The  -P  option 
preserves  the  physical  path  when  treating  symbolic  links,  cd  -P  .  .  changes  the  work- 
ing directory  to  the  parent  directory  of  the  current  directory.  The  shell  parameter  HOME  is 
the  default  arg.  The  parameter  PWD  is  set  to  the  current  directory.  The  shell  parameter 
CDPATH  defines  the  search  path  for  the  directory  containing  arg.  Alternative  directory 
names  are  separated  by  a  colon  (:).  If  CDPATH  is  null  or  undefined,  the  default  value  is 
the  current  directory.  Note  that  the  current  directory  is  specified  by  a  null  path  name 
which  can  appear  immediately  after  the  equal  sign  or  between  the  colon  delimiters  any- 
where else  in  the  path  list.  If  arg  begins  with  a  /,  the  search  path  is  not  used.  Otherwise, 
each  directory  in  the  path  is  searched  for  arg.  See  also  cd(l). 

The  second  form  of  cd  substitutes  the  string  new  for  the  string  old  in  the  current  directory 
name,  PWD  and  tries  to  change  to  this  new  directory. 

The  cd  command  cannot  be  executed  by  rksh. 

echo  [arg  ...] 

See  echo(l)  for  usage  and  description. 
%  eval  [arg  ... ] 

Reads  the  arguments  as  input  to  the  shell  and  executes  the  resulting  command(s). 
%  exec  [arg  ... ] 

Parameter  assignments  remain  in  effect  after  the  command  completes.  If  arg  is  given,  the 
command  specified  by  the  arguments  is  executed  in  place  of  this  shell  without  creating  a 
new  process.  Input/output  arguments  can  appear  and  affect  the  current  process.  If  no 
arguments  are  given,  the  effect  of  this  command  is  to  modify  file  descriptors  as  prescribed 
by  the  input/output  redirection  list.  In  thiscase,  any  file  descriptor  numbers  greater  than  2 
opened  with  this  mechanism  are  closed  when  invoking  another  program. 

%  exit  [n]  Causes  the  shell  to  exit  with  the  exit  status  specified  by  n.  If  n  is  omitted,  the  exit  status  is 
that  of  the  last  command  executed.  An  end-of-file  also  causes  the  shell  to  exit,  except  when 
a  shell  has  the  ignoreeof  option  set  (see  set  below). 

%%  export  [name  [=value]  ...] 

The  given  names  are  marked  for  automatic  export  to  the  envi  ronment  of  subsequently  exe- 
cuted commands. 

fc  [-eename]  [-nir  ]  [first  [last]] 

fc  -e  -  [old=new]  [command  ] 

I  n  the  first  form,  a  range  of  commands  from  first  to  last  is  selected  from  the  last  HIST- 
SIZE  commands  typed  at  the  terminal.  The  arguments  first  and  last  can  be  specified  as  a 
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number  or  string.  A  given  string  is  used  to  locate  the  most  recent  command.  A  negative 
number  is  used  to  offset  the  current  command  number.  The  -1  option  causes  the  com- 
mands to  be  listed  on  standard  output.  Otherwise,  the  editor  program  ename  is  invoked  on 
a  file  containing  these  keyboard  commands.  If  ename  is  not  supplied,  the  value  of  the 
parameter  FCEDIT  (default  /usr/bin/ed)  is  used  as  the  editor.  Once  editing  has 
ended,  the  commands  (if  any)  are  executed.  If  last  is  omitted,  only  the  command  specified 
by  first  is  used.  If  first  is  not  specified,  the  default  is  the  previous  command  for  editing  and 
-16  for  listing.  The  -r  option  reverses  the  order  of  the  commands  and  the  -n  option 
suppresses  command  numbers  when  listing.  In  the  latter,  the  command  is  re-executed 
after  the  substitution  old=new  is  performed. 

fg  [job...]  Brings  each  job  into  the  foreground  in  the  order  specified.  If  no  job  is  specified,  the  current 
job  is  brought  into  the  foreground.  SeeJ  obsfor  a  description  of  the  format  of  job. 

getopts  optstring  name  [arg  ...] 

Checks  arg  for  legal  options.  If  arg  is  omitted,  the  positional  parameters  are  used.  An 
option  argument  begins  with  a  +  or  a  -.  An  option  not  beginning  with  +  or  -,  or  the  argu- 
ment —  ends  the  options,  optstring  contains  the  letters  that  getopts  recognizes.  If  a 
letter  is  followed  by  a  : ,  that  option  is  expected  to  have  an  argument.  The  options  can  be 
separated  from  the  argument  by  blanks. 

getopts  places  the  next  option  letter  it  finds  inside  variable  name  each  time  it  is  invoked 
with  a  +  preceding  it  when  arg  begins  with  a  +.  The  index  of  the  next  arg  is  stored  in 
OPTIND.  Theoption  argument,  if  any,  gets  stored  in  OPTARG. 

A  leading  :  in  optstring  causes  getopts  to  store  the  letter  of  an  invalid  option  in 
OPTARG,  and  to  set  name  to  ?  for  an  unknown  option  and  to  :  when  a  required  option  is 
missing.  Otherwise,  getopts  prints  an  error  message.  The  exit  status  is  non-zero  when 
there  are  no  more  options.  See  also  getopts(l). 

jobs  [-lnp  ]  [job  ...  ] 

Lists  information  about  each  given  job;  or  all  active  jobs  if  job  is  omitted.  The  -1  option 
lists  process  ids  in  addition  to  the  normal  information.  The  -n  option  only  displaysjobs 
that  have  stopped  or  exited  since  last  notified.  The  -p  option  causes  only  the  process 
group  to  be  listed.  SeeJ  obsfor  a  description  of  the  format  of  job. 

kill  [  — sig ]  process  ... 

Sends  either  the  term  (terminate)  signal  or  the  specified  signal  to  the  specified  jobs  or 
processes.  Signals  are  given  either  by  number  or  name  (as  given  in  signal (5),  stripped  of 
the  prefix  SIG).  The  signal  names  are  listed  by  kill  -1.  No  default  exists;  merely  typ- 
ing kill  does  not  affect  the  current  job.  If  the  signal  being  sent  is  TERM  (terminate)  or 
HUP  (hangup),  the  job  or  process  is  sent  a  CONT  (continue)  signal  when  stopped.  The  pro- 
cess argument  can  be  either  a  process  id  or  job.  If  the  first  argument  to  kill  is  a  nega- 
tive integer,  it  i s  i nterpreted  as  a  sig  argument  and  not  as  a  process  group.  See  also  kill(l). 

let  arg  ...  Each  arg  is  a  separate  arithmetic  expression  to  be  evaluated.  See  Arithmetic  Evaluation 
above,  for  a  description  of  arithmetic  expression  evaluation.  The  exit  status  is  0  if  the  value 
of  the  last  expression  is  non-zero,  and  1  otherwise. 

%  newgrp  [arg  ...  ] 

Equivalent  to  exec  newgrp  arg  .... 

print[-Rnprsu[n]]  [arg  ...] 

The  shell  output  mechanism.  With  no  options  or  with  option  -  or  —  the  arguments  are 
printed  on  standard  output  as  described  by  echo(l).  Raw  mode,  -R  or  -r,  ignores  the 
escape  conventions  of  echo.  The  -R  option  prints  all  subsequent  arguments  and  options 
other  than  -n.  The  -p  option  causes  the  arguments  to  be  written  onto  the  pi  pe  of  the  pro- 
cess spawned  with  |  &  instead  of  standard  output.  The  -s  option  causes  the  arguments  to 
be  written  onto  the  history  file  instead  of  standard  output.  The  -u  option  can  be  used  to 
specify  a  one-digit  file  descriptor  unit  number  n  on  which  the  output  is  to  be  placed.  The 
default  is  1.  If  the  option  -n  is  used,  no  new-line  character  is  added  to  the  output. 

pwd  [-l|-P] 

With  no  arguments  prints  the  current  working  directory  (equivalent  to  print  -r  - 
$PWD).  The  -L  option  (default)  preserves  the  logical  meaning  of  the  current  directory  and 
-P  preserves  the  physical  meaning  of  the  current  directory  if  it  is  a  symbolic  link.  See  the 
special  cd  command,  cd(l),  ln(l)),  and  pwd(l). 
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read  [-prsu[n]]  [name]  [?prompt]  [name  ...] 

The  shell  input  mechanism.  One  line  is  read  and  broken  up  into  words  using  the  charac- 
ters in  IFS  as  separators.  In  -r  raw  mode,  \  at  the  end  of  a  line  does  not  signify  line 
continuation.  The  first  word  is  assigned  to  the  first  name,  the  second  word  to  the  second 
name,  etc.,  with  remaining  words  assigned  to  the  last  name.  The  -p  option  causes  the 
input  line  to  be  taken  from  the  input  pipe  of  a  process  spawned  by  the  shell  using  |  &  .  If 
the  -s  option  is  present,  the  input  is  saved  as  a  command  in  the  history  file.  The  option 
-u  can  be  used  to  specify  a  one-digit  file  descriptor  unit  to  read  from.  The  file  descriptor 
can  be  opened  with  the  exec  special  command.  The  default  value  of  n  is  0.  If  name  is 
omitted,  REPLY  is  used  as  the  default  name.  The  return  code  is  0,  unless  an  end-of-file  is 
encountered.  An  end-of-file  with  the  -p  option  causes  cleanup  for  this  process  so  that 
another  process  can  be  spawned.  If  the  first  argument  contains  a  ?,  the  remainder  of  this 
word  is  used  as  a  prompt  when  the  shell  is  interactive.  If  the  given  file  descriptor  is  open 
for  writing  and  is  a  terminal  device,  the  prompt  is  placed  on  this  unit.  Otherwise  the 
prompt  is  issued  on  file  descriptor  2.  The  return  code  is  0,  unless  an  end-of-file  is  encoun- 
tered. See  also  read(l). 

%%  readonly  [name[=value]  ...] 

The  given  names  are  marked  read-only  and  these  names  cannot  be  changed  by  subsequent 
assignment. 

%  return  [n] 

Causes  a  shell  function  to  return  to  the  invoking  script  with  the  return  status  specified  by 
n.  If  n  is  omitted,  the  return  status  is  that  of  the  last  command  executed.  Only  the  low  8 
bits  of  n  are  passed  back  to  the  caller.  If  return  is  invoked  while  not  in  a  function  or 
executi  ng  a  scri  pt  by  the  .  (dot)  built-in  command,  it  has  the  same  effect  as  an  exit  com- 
mand. 

set  [  ±aef  hkmnopstuvx   |   ±o  option  ]  ...  [  ±Aname][arg  ...] 
Thefollowing  options  are  used  for  this  command: 

-A       Array  assignment.  Unset  the  variable  name  and  assign  values  sequentially 

from  the  list  arg.  If  +A  is  used,  the  variable  name  is  not  unset  first, 
-a       All  subsequent  defined  parameters  are  automatically  exported, 
-e       If  the  shell  is  non-interactive  and  if  a  command  fails,  execute  the  ERR  trap, 

if  set,  and  exit  immediately.  This  mode  is  disabled  while  reading  profiles, 
-f  Disablesfilenamegeneration. 

-h  Each  command  whose  name  is  an  identifier  becomes  a  tracked  alias  when 
first  encountered. 

-k  All  parameter  assignment  arguments  (not  just  those  that  precede  the  com- 
mand name)  are  placed  in  the  environment  for  a  command. 

-m  Background  jobs  are  run  in  a  separate  process  group  and  a  line  is  printed 
upon  completion.  The  exit  status  of  background  jobs  is  reported  in  a  comple- 
tion message.  This  option  is  turned  on  automatically  for  interactive  shells. 

-n  Read  commands  and  check  them  for  syntax  errors,  but  do  not  execute  them. 
The  -n  option  is  ignored  for  interactive  shells. 

-o  The  -o  argument  takes  any  of  several  option  names,  but  only  one  option  can 
be  specified  with  each  -o  option.  If  none  is  supplied,  the  current  option  set- 
tings are  printed.  The  -o  argument  option  names  follow: 


allexport 

Same  as  -a. 

bgnice 

All  background  jobs  are  run  at  a  lower  priority. 

errexit 

Same  as  -e. 

emacs 

Activates  an  emacs-style  in-line  editor  for  command 

entry. 

gmacs 

Activates  a   gmacs-style  in-line  editor  for  command 

entry. 

ignoreeof 

The  shell  does  not  exit  on  end-of-file.   The  command 

exit  must  be  used. 

keyword 

Same  as  -k. 

markdirs 

All  directory  names  resulting  from  file  name  generation 

havea  trailing  /  appended. 

monitor 

Same  as  -m. 

noclobber 

Prevents  redirection   >  from  truncating  existing  files. 

Requires  >|  to  truncate  a  file  when  turned  on. 
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noexec 

noglob 

nolog 

nounset 

privileged 

verbose 

trackall 

vi 


vi  raw 
xtrace 


-P 


-s 
-t 
-u 
-v 
-x 


Same  as  -n. 
Same  as -f. 

Do  not  save  function  definitions  in  history  file. 
Same  as -u. 
Same  as -p. 
Same  as -v. 
Same  as  -h. 

Activates  the  insert  mode  of  a  vi-style  in-line  editor 
until  you  press  the  ESC  key  which  puts  you  in  move  mode. 
A  return  sends  the  line. 

Each  character  is  processed  as  it  istyped  in  vi  mode. 
Same  as -x. 

Disables  processing  of  the   $HOME/  .prof  ile  file  and  uses  the  file 
/etc/suid_prof  ile  instead  of  the  ENV  file.  This  mode  is  on  whenever 
the  effective  uid  (gid)  is  not  equal  to  the  real  uid  (gid).  Turning  this  off  causes 
the  effective  uid  and  gid  to  beset  to  the  real  uid  and  gid. 
Sort  the  positional  parameters. 
Exit  after  reading  and  executing  one  command. 
Treat  unset  parameters  as  an  error  when  substituting. 
Print  shell  input  lines  as  they  are  read. 
Print  commands  and  their  arguments  as  they  are  executed. 
Turns  off  -x  and  -v  options  and  stops  examining  arguments  for  options. 
—       Do  not  change  any  of  the  options;  useful  in  setting  $1  to  a  value  beginning 
with  -.  If  no  arguments  follow  this  option,  the  positional  parameters  are 
unset. 

Using  +insteadof  -  before  a  option  causes  the  option  to  be  turned  off.  These  options  can 
also  be  used  when  invoking  the  shell.  The  current  set  of  options  can  be  examined  by  using 
$-. 

Unless  -A  is  specified,  the  remaining  arg  arguments  are  positional  parameters  and  are 

assigned  consecutively  to  $1,  $2          If  neither  arguments  nor  options  are  given,  the 

values  of  all  names  are  printed  on  the  standard  output. 

%  shift  [n]  The  positional  parameters  from  $n+l  ...  are  renamed  $1  default  n  is  1.  The  parame- 
ter n  can  beany  arithmetic  expression  that  evaluates  to  a  non-negative  number  less  than  or 
equal  to  $#. 

test  [expr]  Evaluate  conditional  expression  expr.  See  test(l)  for  usage  and  description.  The  arithmetic 
comparison  operators  are  not  restricted  to  integers.  They  allow  any  arithmetic  expression. 
Four  additional  primitive  expressions  are  allowed: 

-L  file  Trueif  fileisa  symbolic  link, 

filel  -nt  file2  True  if  filel  is  newer  than  file2. 

filel  -ot  file2  True  if  filel  is  older  than  file2. 

filel  -ef  file2  True  if  filel  has  the  same  device  and  i-node  number  as  file2. 

%  times  Print  the  accumulated  user  and  system  times  for  the  shell  and  for  processes  run  from  the 
shell. 

%  trap  [arg]  [sig  ... ] 

arg  is  a  command  read  and  executed  when  the  shell  receives  signal(s)  sig.  (Note  that  arg  is 
scanned  once  when  the  trap  is  set  and  once  when  the  trap  is  taken.)  Each  sig  can  be  given 
as  a  number  or  name  of  the  signal.  Trap  commands  are  executed  in  signal  number  order. 
Any  attempt  to  set  a  trap  on  a  signal  that  was  ignored  upon  entering  the  current  shell  has 
no  effect.  If  arg  is  omitted  or  is  -,  all  traps  for  sig  are  reset  to  their  original  values.  If  arg 
is  the  null  string,  this  signal  is  ignored  by  the  shell  and  by  the  commands  it  invokes.  If  sig 
is  DEBUG,  arg  is  executed  after  each  command.  If  sig  is  ERR,  arg  is  executed  whenever  a 
command  has  a  non-zero  exit  code.  If  sig  is  0  or  EXIT  and  the  trap  statement  is  exe- 
cuted inside  the  body  of  a  function,  the  command  arg  is  executed  after  the  function  com- 
pletes. If  sig  is  0  or  EXIT  for  a  trap  set  outside  any  function,  the  command  arg  is  exe- 
cuted on  exit  from  the  shell.  The  trap  command  with  no  arguments  prints  a  list  of  com- 
mands associated  with  each  signal  number. 

%%  typeset  [±LRZfilrtux[n]]  [namef  =value]]  ... 

Parameter  assignments  remain  in  effect  after  the  command  completes.  When  invoked 
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inside  a  function,  a  new  instance  of  the  parameter  name  is  created.  The  parameter  value 
and  type  are  restored  when  the  function  completes.  The  following  list  of  attributes  can  be 
specified: 

-L  Left  justify  and  remove  leading  blanks  from  value.  If  n  is  non-zero,  it  defines 
the  width  of  the  field.  Otherwise,  it  is  determined  by  the  width  of  the  value  of 
first  assignment.  When  the  name  is  assigned,  the  value  is  filled  on  the  right 
with  blanks  or  truncated,  if  necessary,  to  fit  into  the  field.  Leading  zeros  are 
removed  if  the  -Z  option  is  also  set.  The  -R  option  is  turned  off. 

-R  Right  justify  and  fill  with  leading  blanks.  If  n  is  non-zero,  it  defines  the  width  of 
the  field.  Otherwise,  it  is  determined  by  the  width  of  the  value  of  first  assign- 
ment. The  field  is  left-filled  with  blanks  or  truncated  from  the  end  if  the  param- 
eter is  reassigned.  The  -L  option  is  turned  off. 

-Z  Right  justify  and  fill  with  leading  zeros  if  the  first  non-blank  character  is  a  digit 
and  the  -L  option  has  not  been  set.  If  n  is  non-zero,  it  defines  the  width  of  the 
field.  Otherwise,  it  isdetermined  by  the  width  of  the  value  of  first  assignment. 

-f  Cause  name  to  refer  to  function  names  rather  than  parameter  names.  No 
assignments  can  be  made  to  the  name  declared  with  the  typeset  statement. 
The  only  other  valid  options  are  -t  (which  turns  on  execution  tracing  for  this 
function)  and  -x  (which  allows  the  function  to  remain  in  effect  across  shell  pro- 
cedures executed  in  the  same  process  environment). 

-i  Parameter  is  an  integer.  This  makes  arithmetic  faster.  If  n  is  non-zero,  it 
defines  the  output  arithmetic  base;  otherwise  the  first  assignment  determines 
the  output  base. 

-1  Convert  all  uppercase  characters  to  lowercase.  The  uppercase  -u  option  is 
turned  off. 

-r  Any  given  name  is  marked  "read  only"  and  cannot  be  changed  by  subsequent 
assignment. 

-t  Tag  the  named  parameters.  Tags  are  user  definable  and  have  no  special  mean- 
ing to  the  shell. 

-u  Convert  all  lowercase  characters  to  uppercase  characters.  The  lowercase  -1 
option  is  turned  off. 

-x  Mark  any  given  name  for  automatic  export  to  the  environment  of  subsequently 
executed  commands. 

Using  +  instead  of  -  causes  these  options  to  be  turned  off.  If  no  name  argu- 
ments are  given  but  options  are  specified,  a  list  of  names  (and  optionally  the 
values)  of  the  parameters  that  have  these  options  set  is  printed.  Using  + 
instead  of  -  retains  the  values  to  be  printed.  If  neither  names  nor  options  are 
given,  the  names  and  attributes  of  all  parameters  are  printed. 

ulimit  [n  ]  If  n  is  given,  impose  a  size  limit  of  n  512  byte  blocks  on  files  written  by  child  processes  (files 
of  any  size  can  be  read).  If  n  is  not  given,  the  current  limit  is  printed. 

umask  [mask] 

The  user  file-creation  mask  is  set  to  mask  (see  umask(2)).  mask  can  either  be  an  octal 
number  or  a  symbolic  value  as  described  in  chmod(l).  If  a  symbolic  value  is  given,  the  new 
umask  value  is  the  complement  of  the  result  of  applying  mask  to  the  complement  of  the 
previous  umask  value.  If  mask  is  omitted,  the  current  value  of  the  mask  is  printed.  See 
alsoumask(l). 

unalias  name  ... 

The  parameters  given  by  the  list  of  names  are  removed  from  the  alias  list. 

unset  [-f  ]  name  ... 

The  parameters  given  by  the  list  of  names  are  unassigned;  that  is,  their  values  and  attri- 
butes are  erased.  Read-only  variables  cannot  be  unset.  If  the  -f  option  is  set,  names 
refer  to  function  names.  Unsetting  ERRNO,  lineno,  mailcheck,  optarg,  optind, 
RANDOM,  SECONDS,  TMOUT,  and  _  removes  their  special  meaning  even  if  they  are  subse- 
quently assigned  to. 

%  wait  [job]  Wait  for  the  specified  job  to  terminate  or  stop,  and  report  its  status.  This  status  becomes 
the  return  code  for  the  wait  command.  If  job  is  not  given,  wait  waits  for  all  currently 
active  child  processes  to  termi nate  or  stop.  The  termination  status  returned  is  that  of  the 
last  process.  See  J  obs  for  a  description  of  the  format  of  a  job. 
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whence  [-pv]  name  ... 

For  each  name,  indicate  how  it  would  be  interpreted  if  used  as  a  command  name.  The  -v 
option  produces  a  more  verbose  report.  The  -p  option  does  a  path  search  for  name  even  if 
name  is  an  alias,  a  function,  or  a  reserved  word. 

Invoking  ksh 

If  the  shell  is  invoked  by  exec  (see  exec(2)),  and  the  first  character  of  argument  zero  ($0)  is  -,  the  shell  is 
assumed  to  be  a  login  shell  and  commands  are  read  first  from  /etc/profile.  The  expression 
$  {HOME :  - .  }  /  .profile  is  then  evaluated  and  an  attempt  to  open  the  resulting  filename  is  made.  If 
the  file  is  opened  successfully,  the  file  is  read.  Next,  commands  are  read  from  the  file  named  by  performing 
parameter  substitution  on  the  value  of  the  environment  parameter  ENV,  if  the  file  exists.  If  the  -s  option 
is  not  present  and  arg  is,  a  path  search  is  performed  on  the  first  arg  to  determine  the  name  of  the  script  to 
execute.  When  running  ksh  with  arg,  the  script  arg  must  have  read  permission  and  any  setuid  and  getgid 
settings  are  ignored.  Commands  are  then  read  as  described  below.  The  following  options  are  interpreted 
by  the  shell  when  it  is  invoked: 

-c  string        If  the  -c  option  is  present,  commands  are  read  from  string. 

-s  If  the  -s  option  is  present  or  if  no  arguments  remain,  commands  are  read  from  the 

standard  input.  Shell  output,  except  for  the  output  of  some  of  the  Special  Commands 
listed  above,  is  written  to  file  descriptor  2. 

-i  If  the  -i  option  is  present  or  if  the  shell  input  and  output  are  attached  to  a  terminal, 

the  shell  is  interactive.  In  this  case  Si  GTE  rm  is  ignored  (so  that  kill  0  does  not 
kill  an  interactive  shell)  and  SIGINT  +1  is  caught  and  ignored  (so  that  wait  is  inter- 
ruptible).  I  n  all  cases,  SIGQUIT  is  ignored  by  the  shell.  (See  signal  (5).) 

-r  If  the  -r  option  is  present,  the  shell  is  a  restricted  shell. 

The  remaining  options  and  arguments  are  described  under  the  set  command  above, 
rksh  Only 

rksh  is  used  to  set  up  login  names  and  execution  environments  where  capabilities  are  more  controlled 
than  those  of  the  standard  shell.  Theactionsof  rksh  areidentical  to  those  of  ksh,  except  that  the  follow- 
ing are  forbidden: 

•  Changing  directory  (see  cd(l)) 

•  Setting  the  value  of  SHELL,  ENV,  or  PATH 

•  Specifying  path  or  command  names  containing  / 

•  Redirecting  output  (>,>  |  ,<>,  and  ») 

The  restrictions  above  are  enforced  after  the  .profile  and  ENV  files  are  interpreted. 

When  a  command  to  beexecuted  is  found  to  be  a  shell  procedure,  rksh  invokes  ksh  to  execute  it.  Thus, 
the  end-user  isprovided  with  shell  procedures  accessibleto  the  full  power  of  the  standard  shell,  whilebeing 
restricted  to  a  limited  menu  of  commands.  This  scheme  assumes  that  the  end-user  does  not  have  write  and 
execute  permissions  in  the  same  directory. 

When  a  shell  procedure  is  invoked  from  rksh,  the  shell  interpreter  specified  with  the  #!  magic  inherits 
all  the  restricted  features  of  rksh.  So,  the  shell  procedures  written  for  execution  under  rksh  with  the 
intent  of  utilizing  the  full  power  of  the  standard  shell  should  not  specify  an  interpreter  with  # ! . 

These  rules  effectively  give  the  writer  of  the  .profile  file  complete  control  over  user  actions,  by  per- 
forming guaranteed  set-up  actions  and  leaving  the  user  in  an  appropriate  directory  (probably  not  the  login 
directory). 

The  system  administrator  often  sets  up  a  directory  of  commands  (usually  /usr/rbin)  that  can  be  safely 
invoked  by  rksh.  HP-UX  systems  provide  a  restricted  editor  red  (seeed(l)),  suitablefor  restricted  users. 

COMMAND-LINE  EDITING 
In-line  Editing  Options 

Normally,  each  command  line  typed  at  a  terminal  device  is  followed  by  a  new-line  (carriage-return  or  line- 
feed). If  either  the  emacs,  gmacs,  or  vi  option  is  set,  the  user  can  edit  the  command  line.  An  editing 
option  is  automatically  selected  each  time  the  VISUAL  or  EDITOR  variable  is  assigned  a  value  ending  in 
either  of  these  option  names. 

The  editing  features  require  that  the  user's  terminal  accept  Return  as  carriage  return  without  linefeed  and 
that  a  space  character  must  overwrite  the  current  character  on  the  screen,  adm  terminal  users  should  set 
the  "space/advance"  switch  to  "space".  Hewlett-Packard  terminal  users  should  set  the  straps  to 
"bcGHxZetX". 
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The  editing  modes  enable  the  user  to  look  through  a  window  at  the  current  line.  The  default  window  width 
is  80,  unless  the  value  of  COLUMNS  is  defined.  If  the  line  is  longer  than  the  window  width  minus  two,  a 
mark  displayed  at  the  end  of  the  window  notifies  the  user.  The  mark  is  a  >,  <,  or  *  if  the  line  extends 
respectively  on  the  right,  left,  or  both  side(s)  of  the  window.  As  the  cursor  moves  and  reaches  the  window 
boundaries,  the  window  is  centered  about  the  cursor. 

The  search  commands  in  each  edit  mode  provide  access  to  the  history  file.  Only  strings  are  matched,  not 
patterns,  although  a  leading  "  in  the  string  restricts  the  match  to  begin  at  the  first  character  in  the  line. 

Emacs  Editing  Mode 

This  mode  is  invoked  by  either  the  emacs  or  gmacs  option.  Their  sole  difference  istheir  handlingof  ~T. 
To  edit,  the  user  moves  the  cursor  to  the  point  needing  correction  and  inserts  or  deletes  characters  or 
words.  All  editing  commands  are  control  characters  or  escape  sequences.  The  notation  for  control  charac- 
ters is  circumflex  (")  followed  by  the  character.  For  example,  "F  is  the  notation  for  Ctrl-F.  This  is  entered 
by  pressing  the  f  key  while  holding  down  the  Ctrl  (control)  key.  The  Shift  key  is  not  pressed.  (The  nota- 
tion "?  indicates  the  del  (delete)  key.) 

The  notation  for  escape  sequences  is  M-  followed  by  a  character.  For  example,  M-f  (pronounced  Meta  f)  is 
entered  by  depressing  ESC  (ASCII  033  )  followed  by  f .  M-F  would  be  the  notation  for  ESC  followed  by  Shift 
(capital)  F. 

All  edit  commands  operate  from  any  place  on  the  line  (not  only  at  the  beginning).  Neither  the  Return  nor 
the  Line  Feed  key  is  entered  after  edit  commands,  except  when  noted. 

~F  Move  cursor  forward  (right)  one  character. 

M-f  Move  cursor  forward  one  word.  (The  editor's  idea  of  a  word  is  a  string  of  characters  consist- 

ing of  only  letters,  digits  and  underscores.) 
~B  Move  cursor  backward  (left)  one  character. 

M-b  Move  cursor  backward  one  word. 

"A  M ove  cursor  to  start  of  I i  ne. 

~E  Move  cursor  to  end  of  line. 

*  ]  char  Move  cursor  forward  to  character  char  on  current  line. 

M-~  ]  char       Move  cursor  backward  to  character  char  on  current  line. 
*X"X  I  nterchange  the  cursor  and  mark. 

erase  (User  defined  erase  character  as  defined  by  the  stty(l)  command,  usually  ~H  or  #.)  Delete 

previous  character. 
~D  Delete  current  character. 

eof  End-of-file  character,  normally  ~D,  terminates  the  shell  if  the  current  lineis  null. 

M-d  Delete  current  word. 

M-*H  (M eta-backspace)  Delete  previous  word. 

M-h  Delete  previous  word. 

M-~?  (Meta-DEL)  Delete  previous  word  (if  interrupt  character  is  "?  (del,  the  default)  this  com- 

mand does  not  work). 

~T  Transpose  current  character  with  next  character  in  emacs  mode.  Transpose  two  previous 

characters  in  gmacs  mode. 
~C  Capitalizecurrent  character. 

M-c  Capitalizecurrent  word. 

M-l  Change  the  current  word  to  lowercase. 

~K  Delete  from  the  cursor  to  the  end  of  the  line.  If  preceded  by  a  numerical  parameter  whose 

value  is  less  that  the  current  cursor  position,  delete  from  the  given  position  up  to  the  cur- 
sor. If  preceded  by  a  numerical  parameter  whose  value  is  greater  than  the  current  cursor 
position,  from  the  cursor  up  to  the  given  position. 

~W  Kill  from  the  cursor  to  the  mark. 

M-p  Push  the  region  from  the  cursor  to  the  mark  on  the  stack. 

kill  (User-defined  kill  character,  as  defined  by  the  stty(l)  command,  usually      or  @.)  Kill  the 

entire  current  line.  If  two  kill  characters  are  entered  in  succession,  all  subsequent  consecu- 
tive kill  characters  cause  a  linefeed  (useful  when  using  paper  terminals). 

"Y  Restorelast  item  removed  from  line  (yank  item  back  to  the  line). 

~L  Linefeed  and  print  current  line. 

"@  (Null  character)  Set  mark. 

M-space         (M eta  space)  Set  mark. 

"J  (New  line)  Execute  the  current  line. 

*M  (Return)  Execute  the  current  line. 
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~P  Fetch  previous  command.  Each  time  ~P  is  entered,  the  next  previous  command  in  the  his- 

tory list  is  accessed. 

~N  Fetch  next  command.  Each  time  ~N  is  entered  the  next  command  in  the  history  list  is 

accessed. 

M-<  Fetch  the  least  recent  (oldest)  history  line. 

M->  Fetch  the  most  recent  (youngest)  history  line. 

"Rstring  Reverse  search  history  for  a  previous  command  line  containing  string.  If  a  parameter  of 
zero  is  given,  the  search  is  forward,  string  is  terminated  by  a  Return  or  New-Line.  If 
string  is  preceded  by  a  " ,  the  matched  line  must  begin  with  string.  If  string  is  omitted,  the 
next  command  line  containing  the  most  recent  string  is  accessed.  I  n  this  case  a  parameter 
of  zero  reverses  the  di  recti  on  of  the  search. 

Operate  -  Execute  the  current  line  and  fetch  from  the  history  file  the  next  line  relative  to 
current  line. 

M-digits  (Escape)  Define  numeric  parameter,  the  digits  are  taken  as  a  parameter  to  the  next  com- 
mand. The  commands  that  accept  a  parameter  are  ~F,  ~B,  erase,  ~C,  ~D,  ~K,  ~R,  ~P,  ~N, 
A] ,  M- . ,  M-_,  M-b,  M-c,  M-d,  M-f ,  M-h,  M-l  and  M-~H. 

M-letter  Softkey.  User's  alias  list  is  searched  for  an  alias  by  the  namejetter  and  if  an  alias  of  this 

name  is  defined,  its  value  is  inserted  on  the  input  queue.  This  letter  must  not  be  one  of  the 
above  meta-functions. 

M- .  The  last  word  of  the  previous  command  is  inserted  on  the  line.  If  preceded  by  a  numeric 

parameter,  the  value  of  this  parameter  determines  which  word  to  insert  rather  than  the 
last  word. 

M-_  Same  as  M-.. 

M-*  Attempt  file-name  generation  on  the  current  word. 

M-ESC  File-name  completion.  Replaces  the  current  word  with  the  longest  common  prefix  of  all 

filenames  matching  the  current  word  with  an  asterisk  appended.  If  the  match  is  unique,  a 
/  is  appended  if  the  file  is  a  directory  and  a  space  is  appended  if  the  file  is  not  a  directory. 

M-=  List  files  matching  current  word  pattern  as  if  an  asterisk  were  appended. 

~U  Multiply  parameter  of  next  command  by  4. 

\  Escape  next  character.  Editing  characters,  the  user's  erase,  kill  and  interrupt  (normally 

A?)  characters  can  be  entered  in  a  command  line  or  in  a  search  string  if  preceded  by  a  \. 
The  \  removes  the  next  character's  editing  features  (if  any). 

"V  Display  version  of  theshell. 

M-#  Insert  a  #  at  the  beginning  of  the  line  and  execute  it.  This  causes  a  comment  to  be 

inserted  in  the  history  file. 

Vi  Editing  Mode 

There  are  two  typing  modes.  Entering  a  command  puts  you  into  input  mode.  To  edit,  the  user  enters 
control  mode  by  pressing  ESC  and  moves  the  cursor  to  the  point  needing  correction,  then  inserts  or  deletes 
characters  or  words.  Most  control  commands  accept  an  optional  repeat  count  prior  to  the  command. 

In  vi  mode  on  most  systems,  canonical  processing  is  initially  enabled  and  the  command  is  echoed  again  if 
the  speed  is  1200  baud  or  greater  and  contains  any  control  characters,  or  if  less  than  one  second  has 
elapsed  since  the  prompt  was  printed.  The  ESC  character  terminates  canonical  processing  for  the 
remainder  of  the  command  and  the  user  can  then  modify  the  command  line.  This  scheme  has  the  advan- 
tages of  canonical  processing  with  the  type-ahead  echoing  of  raw  mode. 

Setting  the  viraw  option  always  disables  canonical  processing  on  the  terminal.  This  mode  is  implicit  for 
systems  that  do  not  support  two  alternate  end-of-line  deli  miters,  and  can  be  helpful  for  certain  terminals. 


Input  Edit  Commands 

By  default  the  editor  is  in  input  mode. 


erase  Delete  previous  character,  (erase  is  a  user-defined  erase  character,  as  defined  by  thestty(l) 

command,  usually  "H  or  #.) 
~W  Delete  the  previous  blank  separated  word. 

~D  Terminate  the  shell. 

"V  Escape  next  character.  Editing  characters,  erase  or  kill  characters  can  be  entered  in  a  com- 

mand line  or  in  a  search  string  if  preceded  by  a  "V.  "V  removes  the  next  character's  edit- 
ing features  (if  any). 

\  Escape  the  next  erase  or  kill  character. 
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Motion  Edit  Commands 

These  commands  move  the  cursor.  The  designation  [count]  causes  a  repetition  of  the  command  the  cited 
number  of  times. 

[count]l  Cursor  forward  (right)  one  character. 

[count]w  Cursor  forward  one  alphanumeric  word. 

[countjw  Cursor  to  the  beginning  of  the  next  word  that  follows  a  blank. 

[countje  Cursor  to  end  of  word. 

[count]E  Cursor  to  end  of  the  current  blank-delimited  word, 

[countjh  Cursor  backward  (left)  one  character, 

[countjb  Cursor  backward  one  word. 

[count]B  Cursor  to  preceding  blank  separated  word, 

[count]  |  Cursor  to  column  count.  Default  is  1. 

[countjf  c  Find  the  next  character  c  in  the  current  line. 

[count]FC  Find  the  previous  character  c  in  the  current  line, 

[countjtc  Equivalent  to  f  followed  by  h. 

[count]TC  Equivalent  to  F  followed  by  1. 

[count];  Repeats  the  last  single  character  find  command,  f ,  F,  t,  or  T. 

[count],  Reverses  the  last  single  character  find  command. 

0  Cursor  to  start  of  line. 

A  Cursor  to  first  nonblank  character  in  line. 

$  Cursor  to  end  of  line. 
Search  Edit  Commands 
These  commands  access  your  command  history. 
[count]k 


Fetch  previous  command.  Each  time  k  is  pressed,  the  next  earlier  command  in 
the  history  list  is  accessed. 
Equivalent  to  k. 

Fetch  next  command.  Each  time  j  is  entered,  the  next  later  command  in  the  his- 
tory list  is  accessed. 
Equivalent  to  j. 

The  command  number  count  is  fetched.  The  default  is  the  first  command  in  the 
history  list. 

Search  backward  through  history  for  a  previous  command  containing  string, 
string  is  terminated  by  a  "Return"  or  "New-line".  If  string  is  preceded  by  a  " ,  the 
matched  line  must  begin  with  string.  If  string  is  null,  the  previous  string  is  used. 
Same  as  /  but  search  in  the  forward  direction. 
Search  for  next  match  of  the  last  pattern  to  /  or  ?  commands. 
Search  for  next  match  of  the  last  pattern  to  /  or  ?,  but  in  reverse  direction. 
Search  history  for  the  string  entered  by  the  previous  /  command. 
Text  Modification  Edit  Commands 
These  commands  modify  the  line. 


[count]- 
[countjj 

[count]+ 
[count]G 

/string 


?  string 

n 

N 


a 
A 

[count]cmotion 
c[count]motion 


s 

D 

[count]dmotion 
d[count]motion 


[count]P 
[countjp 

R 


E  nter  i  nput  mode  and  enter  text  after  the  current  character. 
Append  text  to  the  end  of  the  line.  Equivalent  to  $a. 

Move  cursor  to  the  character  position  specified  by  motion,  deleting  all  characters 

between  the  original  cursor  position  and  new  position,  and  enter  input  mode.  If 

motion  is  c,  the  entire  line  is  deleted  and  input  mode  entered. 

Delete  the  current  character  through  the  end  of  line  and  enter  input  mode. 

Equivalent  toc$. 

Equivalent  to  cc. 

Delete  the  current  character  through  end  of  line.  Equivalent  to  d$. 

Move  cursor  to  the  character  position  specified  by  motion,  deleting  all  characters 
between  the  original  cursor  position  and  new  position.  If  motion  is  d,  the  entire 
line  is  deleted. 

Enter  input  mode  and  insert  text  before  the  current  character. 

Insert  text  before  the  beginning  of  the  line.  Equivalent  to  the  two-character 

sequence  Oi. 

PI  ace  the  previous  text  modification  before  the  cursor. 
PI  ace  the  previous  text  modification  after  the  cursor. 

Enter  input  mode  and  replace  characters  on  the  screen  with  characters  you  type  in 
overlay  fashion. 
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[count]rC 

[countjx 

[count]X 

[count]. 

[count]" 

[count]_ 


ESC 

\ 


Other  Edit  Commands 

[count]y  motion 
y[count]motion 

Y 
u 
U 

[count]v 

AL 
AJ 
AM 


@  letter 


Replace  the  current  character  with  c. 
Delete  current  character. 
Delete  preceding  character. 
Repeat  the  previous  text  modification  command. 
I  nvert  the  case  of  the  current  character  and  advance  the  cursor. 
Causes  the  count  word  of  the  previous  command  to  be  appended  at  the  current  cur- 
sor location  and  places  the  editor  in  input  mode  at  the  end  of  the  appended  text. 
The  last  word  is  used  if  count  is  omitted. 

Appends  an  *  to  the  current  word  and  attempts  file  name  generation.  If  no  match 
is  found,  the  bell  rings.  If  a  match  is  found,  the  word  is  replaced  by  the  matching 
string  and  the  command  places  the  editor  in  input  mode. 

Attempt  file  name  completion  on  the  current  word.  Replaces  the  current  word 
with  the  longest  common  prefix  of  all  filenames  matching  the  current  word  with  an 
asterisk  appended.  If  the  match  is  unique,  a  /  is  appended  if  the  file  is  a  directory 
and  a  space  is  appended  if  the  file  is  not  a  directory. 


Yank  current  character  through  character  that  motion  would  move  the  cursor  to 

and  puts  them  into  the  delete  buffer.  The  text  and  cursor  are  unchanged. 

Yanks  from  current  position  to  end  of  line.  Equivalent  to  y$. 

Undo  the  last  text  modifying  command. 

Undoall  the  text  modifying  commands  performed  on  the  line. 

Returns  the  command  fc  -e  ${VlSUAL:-${EDlTOR:-vi} }  count  in  the 

input  buffer.  If  count  is  omitted,  the  current  line  is  used. 

Linefeed  and  print  current  line.  Has  effect  only  in  control  mode. 

(Newline)  Execute  the  current  line,  regardless  of  mode. 

(Return)  Execute  the  current  line,  regardless  of  mode. 

Equivalent  to  l#  followed  by  Return.  Sends  the  line  after  inserting  a  #  in  front 
of  the  line  and  after  each  new-line.  Useful  for  inserting  the  current  command  line 
in  the  history  list  without  executing  it. 

List  the  filenames  that  match  the  current  word  if  an  asterisk  were  appended  to  it. 
The  user's  alias  list  is  searched  for  an  alias  by  the  namejetter  and  if  an  alias  of 
this  name  is  defined,  its  value  is  inserted  on  the  input  queue  for  processing. 


EXTERNAL  INFLUENCES 
Environment  Variables 

lccollate  determines  the  collating  sequence  used  in  evaluating  pattern  matching  notation  for  file  name 
generation. 

lcctype  determines  the  classification  of  characters  as  letters,  and  the  characters  matched  by  character 
class  expressions  in  pattern  matching  notation. 

If  lc  collate  or  lc  ctype  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of 
LANG  is  used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  con- 
tains an  invalid  setting,  ksh  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 


I  nternational  Code  Set  Support 

Si  ngle-byte  character  code  sets  are  supported. 


RETURN  VALUE 

Errors  detected  by  the  shell,  such  as  syntax  errors,  cause  the  shell  to  return  a  non-zero  exit  status.  Other- 
wise, the  shell  returns  the  exit  status  of  the  last  command  executed  (also  see  the  exit  command  above). 
If  the  shell  is  being  used  non-interactively,  execution  of  the  shell  file  is  abandoned.  Runtime  errors 
detected  by  the  shell  are  reported  by  printing  the  command  or  function  name  and  the  error  condition.  If 
the  line  number  on  which  the  error  occurred  is  greater  than  one,  the  line  number  is  also  printed  in  brackets 
( [  ] )  after  the  command  or  function  name. 

WARNINGS 

File  descriptors  10  and  54  through  60  are  used  internally  by  the  Korn  Shell.  Applications  using  these  and 
forking  a  subshell  should  not  depend  upon  them  surviving  in  the  subshell  or  its  descendants. 
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If  a  command  which  is  a  tracked  alias  is  executed,  and  a  command  with  the  same  name  is  installed  in  a 
directory  in  the  search  path  before  the  directory  where  the  original  command  was  found,  the  shell  contin- 
ues to  load  and  execute  the  original  command.  Use  the  -t  option  of  the  alias  command  to  correct  this 
situation. 

If  you  move  the  current  directory  or  one  above  it,  pwd  may  not  give  the  correct  response.  Use  the  cd 
command  with  a  full  path  name  to  correct  this  situation. 

Some  very  old  shell  scripts  contain  a  caret  (")  as  a  synonym  for  the  pipe  character  (|).  Note  however, 
ksh  does  not  recognize  the  caret  as  a  pipe  character. 

If  a  command  is  piped  into  a  shell  command,  all  variables  set  in  the  shell  command  are  lost  when  the  com- 
mand completes. 

Using  the  fc  built-in  command  within  a  compound  command  causes  the  entire  command  to  disappear 
from  the  history  file. 

The  built-in  command  .  file  reads  the  entire  file  before  any  commands  are  executed.  Therefore,  alias 
and  unalias  commands  in  the  file  do  not  apply  to  any  functions  defined  in  the  file. 

Traps  are  not  processed  while  the  shell  is  waiting  for  a  foreground  job.  Thus,  a  trap  on  CHLD  is  not  exe- 
cuted until  the  foreground  job  terminates. 

The  export  built-in  command  does  not  handle  arrays  properly.  Only  the  first  element  of  an  array  is 
exported  totheenvi  ronment. 

Background  processes  started  from  a  non-interactive  shell  cannot  be  accessed  by  using  job  control  com- 
mands. 

In  an  international  environment,  character  ordering  is  determined  by  the  setting  of  lccollate,  rather 
than  by  the  binary  ordering  of  character  values  in  the  machine  collating  sequence.  This  brings  with  it  cer- 
tain attendant  dangers,  particularly  when  using  range  expressions  in  file  name  generation  patterns.  For 
example,  the  command, 


might  be  expected  to  match  all  file  names  beginning  with  a  lowercase  alphabetic  character.  However,  if 
dictionary  ordering  is  specified  by  lc  collate,  it  would  also  match  file  names  beginning  with  an  uppercase 
character  (as  well  as  those  beginning  with  accented  letters).  Conversely,  it  would  fail  to  match  letters  col- 
lated after  z  in  languages  such  as  Danish  or  Norwegian. 

The  correct  (and  safe)  way  to  match  specific  character  classes  in  an  international  environment  is  to  use  a 
pattern  of  the  form: 

rm   [ [ : lower : ] ] * 

This  uses  lc  ctype  to  determine  character  classes  and  works  predictably  for  all  supported  languages  and 
codesets.  For  shell  scripts  produced  on  non-internationalized  systems  (or  without  consideration  for  the 
above  dangers),  it  is  recommended  that  they  be  executed  in  a  non-NLS  environment.  This  requires  that 
LANG,  lccollate,  etc.,  be  set  to  "C"  or  not  set  at  all. 

Be  aware  that  the  value  of  the  IFS  variable  in  the  user's  environment  affects  the  behavior  of  scripts. 

ksh  implements  command  substitution  by  creating  a  pipe  between  itself  and  the  command.  If  the  root  file 
system  is  full,  the  substituted  command  cannot  write  to  the  pipe.  As  a  result,  the  shell  receives  no  input 
from  the  command,  and  the  result  of  the  substitution  is  null.  I  n  particular,  using  command  substitution  for 
variable  assignment  under  such  circumstances  results  in  the  variable  being  silently  assigned  a  null  value. 


rm  [a-z]* 


AUTHOR 


ksh  was  developed  by  AT&T. 


FILES 


/etc/passwd 

/etc/profile 

/  etc/ suid__prof  ile 

$HOME/ .profile 

/tmp/sh* 


to  find  home  directories 

read  to  set  up  system  environment 

security  profile 

read  to  set  up  user's  custom  environment 
for  here-documents 
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SEE  ALSO 

cat(l),  cd(l),  echo(l),  env(l),  getopts(l),  kill(l),  pwd(l),  read(l),  test(l),  time(l),  umask(l),  vi(l),  dup(2), 
exec(2),  fork(2),  gtty(2),  pipe(2),  stty(2),  signal(5),  umask(2),  ulimit(2),  wait(2),  rand(3C),  a.out(4),  profile(4), 
environ(5),  lang(5),  regexp(5). 
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NAME 

ktutil  -  Kerberos  keytab  file  maintenance  utility 

SYNOPSIS 

ktutil 

DESCRIPTION 

The  ktutil  command  invokes  a  subshell  from  which  an  administrator  can  read,  write,  or  edit  entries  in 
a  Kerberos  V5  keytab  or  V4  srvtab  file. 

ktutil  Commands 

list  Display  the  current  key  list.  Alias:  1 

read_kt  keytabfilename      Read  the  Kerberos  V5  keytab  file,  keytabfilename,  into  the  current  key 

list.  Alias:  rkt 

read_st  srvtabfilename      Read  the  Kerberos  V4  srvtabfile,  srvtabfilename,  into  the  current  key  list. 

Alias:  rst 

write_kt  keytab  filename    Write  the   current    key    list   into  the   Kerberos   V5    keytab  file, 

keytab  filename.  Alias:  wkt 

write_st  srvtabfilename    Write  the  current  key  list  into  the  Kerberos  V4  srvtabfile,  srvtabfilename. 

Alias:  wst 

clear_list  Clear  the  current  key  list.  Alias:  clear 

delete_entry  slot  Delete  the  entry  in  slot  number  slot  from  the  current  key  list.  Alias: 

delete 

list_requests  Display  a  listing  of  availablecommands.  Aliases:  lr,  ? 

quit  Quit  or  exit  from  ktutil.  Aliases:  exit,  q 

FILES 

/etc/krb5  .  keytab  Default  location  of  the  keytab  file, 
/etc/srvtab  Default  location  of  the  srvtab  file 

AUTHOR 

ktutil  was  developed  by  the  Massachusetts  I  nstitute  of  Technology. 

SEE  ALSO 

kerberos(5). 
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NAME 

kvno-  print  key  version  numbers  of  Kerberos  principals 

SYNOPSIS 

kvno  [-e  etype]  service!,  [service2,  ...] 

DESCRIPTION 

kvno  acquires  a  service  ticket  for  the  specified  Kerberos  principals  and  prints  out  the  key  version  numbers 
of  each  principal. 

Options 

-e  etype  Specifies  the  encryption  type  which  will  be  requested  for  the  session  key  of  all  the  services 
named  on  the  command  line.  This  is  useful  in  certain  backward  compatibility  situations.  The 
value  of  etype  can  be  one  of  DES-CBC-CRC,  DES-CBC-RAW  or  DES-CBC-MD4. 

servicel,service2      Service  name(s)  or  principal  name(s). 

Environment  Variables 

kvno  uses  the  foil  owing  environment  variable: 

KRB5CCNAME  Location  of  the  credentials  ticket  cache. 
FILES 

/tmp/krb5cc_{uid}     Default  location  of  the  credentials  cache.  {uid}is  the  decimal  Ul  D  of  the  user. 
AUTHOR 

kvno  was  developed  by  FundsXpress,  INC. 
SEE  ALSO 

kdestroy(l),  kerberos(5),  kinit(l),  krb5.conf(4),  Iibkrb5(3). 
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NAME 

last,  lastb-  indicate  last  logins  of  users  and  ttys 
SYNOPSIS 

/usr/bin/last  [-R]  [-number]  [-f  file]  [name  ...]  [tty  ...] 
/usr/bin/lastb  [-R]  [-number]  [-f  file]  [name  ...]  [tty  ...] 

DESCRIPTION 

The  last  command  searches  backwards  through  the  file  /var/adm/wtmp  (which  contains  a  record  of  all 
logins  and  logouts)  for  information  about  a  user,  a  tty,  or  any  group  of  users  and  ttys.  Arguments  specify 
names  of  users  or  ttys  of  interest.  The  names  of  ttys  can  be  given  fully  or  abbreviated.  For  example,  last 
0  is  the  same  as  last  ttyO.  If  multiplearguments  are  given,  the  information  that  applies  to  any  of  the 
arguments  is  printed.  For  example,  last  root  console  lists  all  of  root's  sessions  as  well  as  all  ses- 
sions on  the  console  terminal.  The  last  command  prints  the  sessions  of  the  specified  users  and  ttys,  most 
recent  first,  indicating  when  the  session  began,  the  duration  of  the  session,  and  the  tty  on  which  the  session 
took  place,  last  indicates  if  the  session  is  still  in  progress  or  if  it  was  cut  short  by  a  reboot. 

The  pseudo-user  reboot  logs  each  time  the  system  reboots.  Thus,  last  reboot  is  a  useful  command 
for  evaluating  the  relative  time  between  system  reboots. 

If  last  is  interrupted,  it  indicates  how  far  the  search  has  progressed  in  wtmp.  If  interrupted  by  a  quit 
signal  (generated  by  a  Ctrl-\ ),  last  indicates  how  far  the  search  has  progressed,  then  continues  the 
search. 

The  lastb  command  searches  backwards  through  the  database  file  /var/adm/btmp  to  display  bad 
login  information.  Access  to  /var/adm/btmp  should  be  restricted  to  users  with  appropriate  privileges 
(owned  by  and  readableonly  by  root)  because  it  may  contain  password  information. 

Options 

The  last  and  lastb  commands  recognize  the  following  options  and  arguments: 

(none)      If  no  arguments  are  specified,  last  prints  a  record  of  all  logins  and  logouts  in  reverse 
order,  most  recent  first. 

-R  When  used  with  last  and  lastb,  -R  displays  the  user's  host  name  as  it  is  stored  in  the 

files  /var/adm/wtmp  and  /var/adm/btmp,  respectively.  The  host  name  is  displayed 
between  the  tty  nameand  the  user's  login  time. 

-number  Limits  the  report  to  number  of  lines. 

-ffile     Use  file  as  the  name  of  the  accounting  file  instead  of  /var/adm/wtmp  or 
/var/ adm/btmp . 

AUTHOR 

last  was  developed  by  the  University  of  California,  Berkeley  and  HP. 
FILES 

/var/adm/btmp   Bad  login  database 
/var/adm/wtmp   Login  database 

SEE  ALSO 

login(l),  utmp(4). 
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NAME 

lastcomm  -  show  last  commands  executed  in  reverse  order 
SYNOPSIS 

lastcomm  [commandname]  ...    [username]  ...    [terminal name]  ... 
DESCRIPTION 

lastcomm  gives  information  on  previously  executed  commands.  If  no  arguments  are  specified, 
lastcomm  prints  information  about  all  the  commands  recorded  in  the  accounting  file, 
/var/adm/pacct  during  the  current  accounting  file's  lifetime.  If  called  with  arguments,  only  account- 
ing entries  with  a  matching  command  name,  user  name,  or  terminal  name  are  printed.  For  example,  to 
producea  listing  of  all  executions  of  commands  named  a. out  by  user  root  on  terminal  ttydO  use: 

lastcomm  a . out  root  ttydO 

For  each  process  entry,  the  following  are  printed. 

•  N  ame  of  the  user  who  ran  the  process. 

•  Flags,  as  accumulated  by  the  accounting  facilities  in  the  system. 

•  Command  name  under  which  the  process  was  called. 

•  Amount  of  cpu  time  used  by  the  process  (in  seconds). 

•  What  time  the  process  started. 
Flags  are  encoded  as  follows: 

S       Command  was  executed  by  a  user  who  has  appropriate  privileges. 
F       Command  ran  after  a  fork,  but  without  a  following  exec. 
D       Command  terminated  with  the  generation  of  a  core  file. 
X      Command  was  terminated  with  the  signal  SIGTERM. 


FILES 


/ var / adm/ pacct 


current  file  for  per-process  accounting 


AUTHOR 


lastcomm  was  developed  by  the  University  of  California,  Berkeley. 


SEE  ALSO 

last(l),  acct(4),  acctsh(lM),  core(4). 
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NAME 

Id  -  link  editor 

SYNOPSIS 

The  link  editor.   Common  options: 

Id  [-bdmnqrstvxzEGIOPQVZ]  [-a  search]  [-c  filename]  [-dynamic] 
[-e  epsym]  [-h  symbol]  ...    [-lx  |  file]  ...    [-1:  library] 
[-m]  [-noshared]  [-o  outfile]  [-u  symbol  ]  ...    [-y  symbol  ]  ... 

[-B  bind]  [-D  offset]  [-L  dir]  ...    [-R  offset]  [-Pd]  [-pd  file]  [-pf  file]  [+b  pathjist] 

[+compat]  [+copyobj debug]  [+df  file] 

[+e  symbol  ]  [+ee  symbol  ]  [+fb]  [+fbu]  [+gst] 

[+gstsize  size]  [+h  internalname]  [+help]  [+k]  [+n] 

[+nocopyobj debug]  [+noob jdebug  ]  [+ob jdebugonly]  [+pd  size] 

[+pgm  name]  [+pi  size]  [+s]  [+std]  [+tools]  [+v [no]  shlibunsats] 

[+vallcompatwarnings]  [+v [no]  compat warnings]  [+FP  flag] 

[+1  symbol]  [+0  [no]  f  astaccess]  [+0  [no]  procelim]  [  +Oreusedir=dir  ] 

[+Oselectivepercent  n]  [+Oselectivesize  size]  [+0selective03] 

[+Ostaticprediction] 

32  Bit  (SOM)  Link  Editor  options: 

Id  [-NST]  [-A  name]  [-C  n]  [-F1]  [-Fw]  [-Fz]  [+cdp  oldpath:newpath] 
[+cg  pathname]  [+dpv]  [+filter  shared  l  i  brary  path  ] 
[+gstbuckets  size]  [+nosmartbind]  [+plabel_cache  flag] 

64  Bit  (ELF)  Link  Editor  options: 

Id  [-k  filename]  [+fini  function]  [+ild]  [+ildnowarn]  [+ildpad  percentage]  [+ildrelink] 
[+init       function]      [+interp       file]      [+ [no]  allowunsats]      [+ [no]  f  orceload] 
[+hideallsymbols]  [+nodef aultmap]  [+noenwar]  [+nodynhash] 
[+nosectionmerge]  [+paddata  pagesize]  [+padtext  pagesize]  [+pdzero] 
[+stripunwind]  [+vtype  type] 

DESCRIPTION 

Id  takes  one  or  more  object  files  or  libraries  as  input  and  combines  them  to  produce  a  single  (usually  exe- 
cutable) file.  In  doing  so  it  resolves  references  to  external  symbols,  assigns  final  addresses  to  procedures 
and  variables,  revises  code  and  data  to  reflect  new  addresses  (a  process  called  "relocation"),  and  updates 
symbolic  debug  information  when  present  in  the  file.  By  default,  Id  produces  an  executable  file  that  can 
be  run  by  the  HP-UX  loader  exec()  (see  exec(2)).  Alternatively,  the  linker  can  generate  a  relocatable  file 
that  is  suitablefor  further  processing  by  Id  (see  -r  below).  It  can  alsogeneratea  shared  library  (see  -b 
below).  The  linker  marks  the  output  file  non-executable  if  there  are  any  duplicate  symbols  or  any 
unresolved  external  references  remain.  Id  may  or  may  not  generate  an  output  file  (see  +k  option)  if  any 
other  errors  occur  during  its  operation. 

Id  recognizes  three  kinds  of  input  files:  object  files  created  by  the  compilers,  assembler,  or  linker  (also 
known  as  .o  files),  shared  libraries  created  by  the  linker,  and  archives  of  object  files  (called  archive 
libraries).  An  archive  library  contains  a  table  of  all  the  externally-visible  symbols  from  its  component  object 
files.  (The  archiver  command  ar(l)  creates  and  maintains  this  index.)  Id  uses  this  table  to  resolve  refer- 
ences to  external  symbols. 

Id  processes  files  in  the  same  order  as  they  appear  on  the  command  line.  It  includes  code  and  data  from 
an  archive  library  element  if  and  only  if  that  object  module  provides  a  definition  for  a  currently  unresolved 
reference  within  the  user's  program.  It  is  common  practice  to  list  libraries  following  the  names  of  all  sim- 
ple object  files  on  the  command  line. 

Code  and  data  from  shared  libraries  is  never  copied  into  an  executable  program.  The  dynamic  loader 
/usr/lib/dld.  si  on  32-bit  links  is  invoked  at  startup  time  by  the  startup  file  crtO.o  if  a  program 
uses  shared  libraries.  Identical  copies  of  crtO  .  o  can  be  found  in  either  /usr/ccs/lib/crtO  .  o  or 
/opt/langtools/lib/crtO .  o.  For  64-bit  mode,  the  dynamic  loader  is 
/usr/lib/pa20_64/dld.  si  and  is  invoked  by  exec  for  those  programs  that  use  shared  libraries. 
crtO  .  o  is  not  required  in  shared  bound  links.  The  dynamic  loader  attaches  each  required  library  to  the 
process  and  resolves  all  symbolic  references  between  the  program  and  its  libraries. 

The  text  segment  of  a  shared  library  is  shared  among  all  processes  that  use  the  library;  each  process  using 
the  library  receives  its  own  copy  of  the  data  segment.  If  pxdb  -s  on  has  been  run  on  the  executable 
that  loads  the  library,  the  text  segment  of  a  shared  library  is  mapped  privately  for  each  process  running  the 
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executable.  Id  recursively  examines  the  dependencies  of  shared  libraries  used  by  a  program  that  was 
created  by  Id.  If  Id  does  not  find  a  supporting  shared  library  at  the  path  recorded  in  the  dependency  list 
of  a  shared  library,  and  if  the  dependency  is  the  result  of  an  -1  argument  used  when  the  shared  library 
was  created,  Id  will  search  all  the  directories  that  it  would  search  for  a  library  that  was  specified  with  -1 
(see  -L  and  LPATH). 

Environment  Variables 

Arguments  can  be  passed  to  the  linker  through  the  LDOPTS  environment  variable  as  well  as  on  the  com- 
mandline.  The  I  inker  gets  the  value  of  LDOPTS  and  places  its  contents  before  any  arguments  on  the  com- 
mand line. 

The  LD_PXDB  environment  variable  defines  the  full  execution  path  for  the  debug  preprocessor  pxdb. 
The  default  value  is  /opt/langtools/bin/pxdb.  Id  invokes  pxdb  on  its  output  file  if  that  file  is 
executable  and  contains  debug  information.  To  defer  invocation  of  pxdb  until  the  first  debug  session,  set 
LD_PXDB  to /bin/true . 

The  LPATH  environment  variable  can  be  used  to  specify  default  directories  to  search  for  library  files.  See 
the  -1  option. 

Options 

Thecommon  Id  options  are  listed  first,  followed  by  the  options  supported  only  in  a  32-bit  linker,  and  then 
the  options  only  supported  in  a  64-bit  linker. 

-a  search  Specify  whether  shared  or  archive  libraries  are  searched  with  the  -1  option.  The 
value  of  search  should  be  one  of  archive,  shared,  archive_shared, 
shared_archive,  or  default.  This  option  can  appear  more  than  once,  inter- 
spersed among  -1  options,  to  control  the  searching  for  each  library.  Thedefault  isto 
use  the  shared  version  of  a  library  if  one  is  available,  or  the  archive  version  if  not. 

If  either  archive  or  shared  isactive,  only  the  specified  library  type  is  accepted. 

If  archive_shared  is  active,  the  archive  form  is  preferred,  but  the  shared  form  is 
allowed. 

If  shared_archive  is  active,  the  shared  form  is  preferred  but  the  archive  form  is 
allowed. 

-b  Create  a  shared  library  rather  than  a  normal  executable  file.  Object  files  processed 

with  this  option  must  contain  position-independent  code  (PIC).  See  the  discussion 
of  PIC  in  cc(l),  CC(1)  (part  of  the  optional  C++ compiler  documentation),  f77(l),  pc(l), 
as(l),  and  Linker  and  Libraries  OnlineUser  Guide. 

-c  filename  Read  Id  options  from  a  file.  Each  line  contains  zero  or  more  arguments  separated  by 
white  space.  Each  line  in  the  file,  including  the  last  line,  must  end  with  a  newline 
character.  A  #  character  implies  that  the  rest  of  the  line  is  a  comment.  To  escape  a 
#  character,  use  the  sequence  ##. 

-d  Force  definition  of  "common"  storage;  that  is,  assign  addresses  and  sizes,  for  -r  out- 

put. 

-e  epsym  Set  the  default  entry  point  address  for  the  output  file  to  be  that  of  the  symbol  epsym. 
(This  option  only  applies  to  executable  files.) 

-h  symbol  Prior  to  writing  the  symbol  tableto  the  output  file,  mark  this  name  as  "local"  so  that 
it  is  no  longer  externally  visible.  This  ensures  that  this  particular  entry  will  not  clash 
with  a  definition  in  another  file  during  future  processing  by  Id. 

More  than  one  symbol  can  be  specified,  but  -h  must  precede  each  one.  If  used  when 
building  a  shared  library  or  program,  this  option  prevents  the  named  symbol  from 
being  visible  to  the  dynamic  loader. 

-lx  Search  a  library  libx.a  or  libx.sl,  where  x  is  one  or  more  characters.  The 

current  state  of  the  -a  option  determines  whether  the  archive  ( .  a)  or  shared  ( .  si) 
version  of  a  library  is  searched.  Because  a  library  is  searched  when  its  name  is 
encountered,  the  placement  of  a  -1  is  significant.  By  default,  32-bit  libraries  are 
located  in  /usr/lib  and  /usr/ccs/lib .  64-bit  libraries  are  located  in 
/usr/lib/pa20_64.  If  the  environment  variable  LPATH  is  present  in  the  user's 
environment,  it  should  contain  a  colon-separated  list  of  directories  to  search.  These 
directories  are  searched  instead  of  the  default  directories,  but  -L  options  can  still  be 
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used.  If  a  program  uses  shared  libraries,  the  dynamic  loader  /usr/lib/dld.  si 
for  32-bit  or  /usr/lib/pa20_64/dld. si  for  64-bit  will  attempt  to  load  each 
library  from  the  same  directory  in  which  it  was  found  at  link  time  (see  the  +s  and 
+b  options). 

-1 :  library  Search  the  library  specified.  Similar  to  the  -1  option  except  the  current  state  of  the 
-a  option  is  not  important.  The  library  name  can  be  any  valid  filename.  (Note  that 
previous  releases  required  that  the  library  name  contain  the  prefix  lib  and  end  with 
a  suffix  of  .  a  or  .  si.) 

This  option  produces  a  load  map  on  the  standard  output. 

This  option  is  accepted  but  ignored  by  the  64-bit  Id.  Generate  an  executable  output 
file  with  file  type  SHARE_MAGIC.  This  is  the  default.  This  option  is  incompatible 
with  -N  and  -q. 

-ooutfile       Produce  an  output  object  file  named  outfile  (a.  out  if  -o  outfile  is  not  specified). 

-q  This  option  is  ignored  for  64-bit  links.  Generate  an  executable  output  file  with  file 

type  DEMAND_MAGIC .  Thisoption  is  incompatible  with  -n,  -N,  and -Q. 

-r  Retain  relocation  information  in  the  output  file  for  subsequent  re-linking.  The  Id 

command  does  not  report  undefined  symbols.  Thisoption  cannot  be  used  when  build- 
ing a  shared  library  (  -b  )  or  in  conjunction  with  -A  or  +ild  incremental  linking 
options. 

-s  Strip  the  output  file  of  all  symbol  table,  relocation,  and  debug  support  information. 

This  might  impair  or  prevent  the  use  of  a  symbolic  debugger  on  the  resulting  pro- 
gram. This  option  is  incompatible  with  -r.  (The  strip(l)  command  also  removes  this 
information.)  This  option  is  incompatible  with  +ild.  (The  incremental  linking 
requires  the  parts  of  the  output  load  module  which  are  stripped  out  with  -s  option.) 

-t  Print  a  trace  (to  standard  output)  of  each  input  file  as  Id  processes  it. 

-u  symbol  Enter  symbol  as  an  undefined  symbol  in  the  symbol  table.  The  resulting  unresolved 
reference  is  useful  for  linking  a  program  solely  from  object  files  in  a  library.  More 
than  one  symbol  can  be  specified,  but  each  must  be  preceded  by  -u. 

-v  Display  verbose  messages  during  linking.  For  each  library  module  that  is  loaded,  the 

linker  indicates  which  symbol  caused  that  moduleto  beloaded. 

-x  Strip  local  symbols  from  the  output  file.  This  reduces  the  size  of  the  output  file 

without  impairing  the  effectiveness  of  object  file  utilities.  This  option  is  incompatible 
with  the  -r  option.  This  option  is  incompatible  with  the  +ild  option.  (The  incre- 
mental linking  requires  the  parts  of  the  output  load  module  which  are  stripped  out 
with  the  -x  option. 

Note:  use  of  -x  might  affect  the  use  of  a  debugger. 

-y  symbol  Indicate  each  file  in  which  symbol  appears.  More  than  one  symbol  can  be  specified, 
but  each  must  be  preceded  by  -y. 

-z  Arrange  for  run-time  dereferencing  of  null  pointers  to  produce  a  SIGSEGV  signal. 

(This  is  the  complement  of  the  -Z  option.) 

-B  bind  Select  run-time  binding  behavior  of  a  program  using  shared  libraries  or  the  binding 

preference  in  building  a  shared  library.  The  most  common  values  for  bind  are: 

deferred 

Bind  addresses  on  first  reference  rather  than  at  program  start-up  time.  This  is 
the  default. 

immediate 

Bind  addresses  of  all  symbols  immediately  upon  loading  the  library.  Commonly 
followed  by  -B  nonfatal  to  allow  procedure  calls  that  cannot  be  resolved  at 
program  start-up  to  be  resolved  on  first  reference. 

Since  -B  nonfatal  suppresses  messages  about  unresolved  symbols,  also 
specify  -B  verbose  to  display  those  messages. 

See  the  example  below. 
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nonfatal 

If  also  using  -B  immediate,  for  code  symbols  that  could  not  be  bound  at  pro- 
gram startup,  defer  binding  them  until  they  are  referenced.  See  description  of 
-B  immediate  above. 

Since  -B  nonfatal  suppresses  messages  about  unresolved  symbols,  also 
specify  -B  verbose  to  display  those  messages. 

restricted 

Causes  the  search  for  a  symbol  definition  to  be  restricted  to  those  symbols  that 
were  visible  when  the  library  was  loaded. 

symbolic 

Used  only  when  building  a  shared  library  (with  the  -b  option),  this  option 
causes  all  unresolved  symbols  inside  a  library  to  be  resolved  internally  if  possi- 
ble. By  default,  unresolved  symbols  are  resolved  to  the  most  visible  definition  in 
the  library  or  outside  of  the  library. 

verbose 

Display  verbose  messages  when  binding  symbols.  This  is  the  default  except  when 
-B  nonfatal  is  specified.  In  that  case,  -B  verbose  must  be  explicitly 
specified  to  get  verbose  messages. 

See  the  +help  option  or  the  HP-UX  Linker  and  Libraries  User's  Guide  manual  for 
more  information  on  the  uses  of  binding  modes. 

-D  offset         Set  the  origin  (in  hexadecimal)  for  the  data  segment. 

When  used  with  the+ild  option,  if  you  change  the  offset  after  the  initial  incremental 
link,  the  linker  performs  an  initial  incremental  link  automatically. 

-E  This  option  is  accepted  but  ignored  by  the  64-bit  Id.  Mark  all  symbols  defined  by  a 

program  for  export  to  shared  libraries.  By  default,  Id  marks  only  those  symbols  that 
are  actually  referenced  by  a  shared  library  seen  at  link  time. 

-G  Strip  all  unloadable  data  from  the  output  file.  This  option  is  typically  used  to  strip 

debug  information. 

-I  Instrument  the  code  to  collect  profile  information  upon  execution.  The  profile  data 

gathered  during  program  execution  can  be  used  in  conjunction  with  the  -P  option. 
32-bit  programs  linked  with  this  option  should  use  the  startup  file 
/opt/langtools/lib/icrtO  .o.  This  option  should  not  be  used  with  the  -P, 
-A,  -O,  +ild,  or  +0  options. 

-L  dir  Search  for  libx .  a  or  libx  .si  in  dir  before  looking  in  default  locations.  More  than 

one  directory  can  be  specified,  but  each  must  be  preceded  by  -L.  The  -L  option  is 
effective  only  if  it  precedes  the  -1  option  on  the  command  line. 

-O  Turn  on  linker  optimizations.  Currently  the  optimizations  include  the  elimination  of 

unnecessary  ADDIL  instructions  from  the  code  in  the  executable  file  (32-bit  only), 
and  the  removal  of  dead  procedures. 

-O  is  passed  to  the  linker  by  the  compilers  when  the  +04  compiler  option  isselected. 
This  option  is  incompatible  with  the  +ild  option. 

For  more  details  on  linker  optimizations  refer  to  the  +help  option  or  the  HP-UX 
Linker  and  Libraries  User's  Guide  manual. 

-P  Examine  the  data  file  produced  by  an  instrumented  program  (see  the  -I  option)  to 

perform  profile  based  optimizations  on  the  code.  This  option  should  not  be  used  with 
the  -A  or  +ild  options. 

-Q  Ignored  for  64-bit  links.  Generate  an  executable  output  file  with  file  type 

EXEC_MAGIC  or  SHARE_MAGIC,  depending  on  whether  -N  or  -n  is  specified. 
This  is  the  default.  This  option  is  incompatible  with  -q. 

-R  offset         Set  the  origin  (in  hexadecimal)  for  the  text  (i.e.,  code)  segment. 

When  used  with  the  +ild  option,  if  you  change  the  offset  after  the  initial  incremen- 
tal link,  the  linker  performs  an  initial  incremental  link  automatically. 
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-V  Output  a  messagegiving  information  about  the  version  of  Id  being  used. 

-Z  Allow  run-time  dereferencing  of  null  pointers.  See  the  discussions  of  -Z  and  pointers 

incc(l).  (This  is  the  complement  of  the  -z  option.) 

-Pd  Reorder  debuggable  functions.  Ordinarily  -P  does  not  reorder  functions  from  .o 

files  with  debugging  information,  because  reordering  renders  them  non-debuggable. 
This  option  overrides  this  and  reorders  the  functions. 

-PD  filename  Save  link  order  file  generated  by  fdp  during  linking  with  -P  option  into  user- 
specified  file.  This  option  is  incompatible  with  the +ild  option. 

-PF  filename  I  ndicateto  the  linker  to  use  the  specified  file  for  the  linker  file  instead  of  generating  it 
using  /usr/ccs/bin/f  dp.  This  option  is  incompatible  with  the  +ild  option. 

-dynamic  This  allows  the  linker  to  create  a  program  which  can  use  shared  libraries.  This  is  the 
default  for  64-bit  links  unless  +compat  is  used.  In  32-bit  mode,  the  linker  creates  a 
static  executable  if  there  are  no  shared  libraries  on  thelink  line. 

-noshared    This  option  forces  the  linker  to  create  a  fully  archive  bound  program. 

+b  path  list  Specify  a  colon-separated  list  of  directories  (embedded  path)  to  be  searched  at  pro- 
gram run-time  to  locate  shared  libraries  needed  by  the  executable  output  file  that 
were  specified  with  either  the  -lor  -1:  option.  An  argument  consisting  of  a  single 
colon  ( : )  indicates  that  Id  should  build  the  list  using  all  the  directories  specified  by 
the  -L  option  and  the  LPATH  environment  variable  (see  the  +s  option). 

+compat  This  option  is  ignored  for  32-bit  links.  This  option  turns  on  compatibility  mode  in  the 
linker  —  64-bit  links  mimic  behavior  of  32-bit  links). 

+copyob  j  debug 

Copy  obj debug  space. 

+df  file  Used  together  with  the  -P  option,  this  option  specifies  that  fileshould  be  used  as  the 
profile  database  file.  The  default  value  is  flow. data.  See  the  discussion  of  the 
FLOW_DATA  environment  variablefor  more  information.  This  option  is  incompatible 
with  the  +ild  option. 

+e  symbol  When  building  a  shared  library  or  program,  mark  the  symbol  for  export  to  the 
dynamic  loader.  Only  symbols  explicitly  marked  are  exported.  When  building  a 
shared  library,  calls  to  symbols  that  are  not  exported  are  resolved  internally. 

+ee  symbol  This  option  is  similar  to  the  +e  option  in  that  it  exports  a  symbol.  However,  unlike 
the  +e  option,  +ee  does  not  alter  the  visibility  of  any  other  symbol  in  the  file.  In  a 
32-bit  link  or  +compat  mode  64-bit  link,  it  has  the  effect  of  exporting  the  specified 
symbol  without  hiding  any  of  the  symbols  exported  by  default.  I  n  a  64  +std  link,  all 
symbols  are  exported  by  default,  so  +ee  is  not  necessary  to  make  a  symbol  visible. 
However,  it  has  the  additional  side  effect  of  identifying  the  symbol  as  necessary,  so 
that  it  will  not  be  removed  when  using  dead  code  elimination  (+Oprocelim).  Of 
course,  +ee  still  retains  its  export  behavior  if  an  option  such  as +hideallsymbols 
is  also  given. 

+fb  Instructs  the  linker  to  run  the  fastbind  tool  on  the  executable  it  has  produced.  The 

executable  should  be  linked  with  shared  libraries.  For  more  details  refer  to  fast- 
bind(l),  the+help  option,  or  the  HP-UX  Linker  and  Libraries  User's  Guide  manual. 
This  option  is  incompatible  with  the  +ild  option. 

+fbu  Pass  the  -u  option  to  the  fastbind  tool.  For  more  details  refer  to  fastbind(l),  the 

+help  option,  or  the  HP-UX  Linker  and  Libraries  User's  Guidemanual.  This  option 
is  incompatible  with  the  +ild  option. 

+gst  Enable  the  global  symbol  table  hash  mechanism,  used  to  look  up  values  of  symbol 

import/export  entries.  The  +gst  and  related  options  provide  performance  enhance- 
ments through  use  of  global  symbol  table  which  improves  searching  for  exported  sym- 
bols. See  did. si (5)  and  the  HP-UX  Linker  and  Libraries  OnlineUser  Guidefor  more 
information. 

-Hgstsize  size 

Request  a  particular  hash  array  size  using  the  global  symbol  table  hash  mechanism. 
The  default  value  is  1103.  The  value  can  be  overridden  at  runtime  by  setting  the 
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_HP_DLDOPTS  environment  variableto  the  value  -symtab_size  prime  number. 
You  can  set  the  value  using  chatr  +gstsize  sizefile. 

+h  internalname 

When  building  a  shared  library,  record  internal  name  as  the  name  of  the  library. 
When  the  library  is  used  to  link  another  executable  file  (program  or  shared  library), 
this  internal  name  is  recorded  in  the  library  list  of  the  resulting  output  file  instead  of 
the  file  system  pathname  of  the  input  shared  library. 

That  is,  if  +h  isnot  used,  the  shared  library  does  not  havean  internal  name  and  when 
an  executable  is  built  with  the  shared  library,  the  linker  records  the  library  name  that 
it  looks  at. 

If  internal  nameis  a  fully-qualified  pathname,  it  is  recorded  as  is  in  the  library  list 
of  any  executable  file  it  is  subsequently  linked  against,  internal  name  is  a  relative 
pathname  or  no  directory  component  was  specified,  internal  name  is  appended  to 
the  file  system  directory  component  of  the  input  shared  library  in  the  library  list  of 
any  executable  file  it  is  subsequently  linked  against. 

If  more  than  one  +h  option  is  seen  on  the  link  line,  the  first  one  is  used  and  a  warning 
message  is  emitted. 

+help  Starts  the  help  window  utility  HP-UX  Linker  and  Libraries  OnlineUser  Guide  which 

comes  with  some  HP  compilers.  (You  must  be  running  the  X  window  system  and  your 
DISPLAY  environment  variable  must  be  set  to  the  name  of  your  workstation  or  X  ter- 
minal.) For  more  information,  refer  to  the  HP-UX  Linker  and  Libraries  User's  Guide 
manual.  See  manual s(5)  for  ordering  information. 

+k  Direct  the  linker  to  only  create  an  executable  if  there  were  no  errors  encountered  dur- 

ing the  link.  If  there  were  errors  found  (system  errors  or  unresolved  references),  the 
output  file  will  be  removed. 

+n  Causes  the  linker  to  load  all  object  modules  before  searching  any  archive  or  shared 

libraries.  Then  it  searches  the  archive  and  shared  libraries  specified  on  the  command 
line  in  left  to  right  order.  Repeats  the  left  to  right  search  of  the  libraries  on  the  com- 
mand line  until  there  are  no  more  unsatisfied  symbols,  or  the  last  search  added  no 
new  definitions.  This  option  is  useful  if  two  libraries  are  specified  that  have  symbol 
dependencies  on  each  other. 

-Hnocopyob  j  debug 

Do  not  copy  objdebug  space.  Use  this  option  (with  -r  object  files  on  the  link  line)  to 
suppress  the  default  behavior  of  copying  LI  NKMAP  space  to  the  executable  file  . 

+noob j debug 

Override  the  +objdebug  compiler  option,  and  copy  all  debug  information  to  the 
executable  file. 

When  used  with  -g,  +objdebug  leaves  debug  information  in  the  object  files  instead 
of  copying  it  to  the  executable  file  at  link  time,  resulting  in  shorter  link  times  and 
smaller  executables.  The  compile-time  default,  +noobj debug,  copies  the  debug 
information  totheexecutablefile. 

When  you  specify  -g  when  compiling,  the  compiler  places  symbolic  debugging  infor- 
mation into  the  object  files.  By  default,  the  linker  calls  pxdb  which  compacts  this 
debug  information  and  copies  it  to  the  executable  file.  When  +objdebug  was  used 
at  compile  time,  the  linker  leaves  the  debug  information  in  the  object  files.  To  debug 
the  executable  file,  the  HP  WDB  debugger  must  have  access  to  the  object  files.  If  you 
move  the  object  files,  use  HP  WDB's  objdir  command  to  tell  it  where  the  object  files 
are.  (The  HP  DDE  debugger  does  not  support  this  option.)  The  +objdebug  option 
reduces  link  time  and  the  size  of  the  executable  file  by  avoiding  this  copying  of  debug 
information. 

The  compile-time  default  is  +noobjdebug .  If  the  linker  detects  any  object  files  that 
were  compiled  with  +objdebug,  it  leaves  the  debug  information  in  those  files.  Any 
object  files  not  compiled  with  +objdebug  have  their  debug  information  copied  into 
the  executable  file.  You  can  leave  debug  information  in  some  object  files  and  not  in 
others. 
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When  archive  members  are  not  compiled  with  +objdebug  (and  they  contain  debug 
information,  that  is,  they  were  compiled  with  -g),  the  debug  information  from  the 
archive  members  is  copied  into  the  a.  out  by  default.  The  linker  does  not  copy  debug 
information  from  shared  libraries  into  the  a. out,  regardless  of  whether  they  are 
compiled  with  +objdebug  or  +noobjdebug. 

Use  the  +noobjdebug  option  when  linking  to  explicitly  tell  the  linker  to  copy  all 
debug  information  to  the  executable  file,  even  from  files  compiled  with  +objdebug. 

+ob  j  debugonly 

Ignore  debug  information  from  non-objdebug  objects  or  archives  and  proceed  in 
+ob  jdebug  mode.  This  option  can  be  passed  from  the  C  or  C++ compiler  command 
line  as  -Wl,  +ob jdebugonly.  If  you  are  debugging  only  files  compiled  with  the 
+objdebug  option,  +ob jdebugonly  can  improve  link  time  by  instructing  the 
linker  to  bypass  the  processing  of  debug  information  from  files  compiled  with 
+noobjdebug.  With  the  +ob jdebugonly  option,  the  linker  suppresses  the  call 
topxdb. 

Request  a  particular  virtual  memory  page  size  that  should  be  used  for  data.  Sizes  of 
4K,  16K,  64K,  256K,  1M,  4M,  16M,  64M,  256M,  D,  and  L  are  supported.  A  size  of  D 
allows  the  kernel  to  choose  what  page  size  should  be  used.  A  size  of  L  will  result  in 
using  the  largest  page  size  available.  The  actual  page  size  may  vary  if  the  requested 
size  cannot  be  fulfilled. 

Used  together  with  the  -P  option,  this  option  specifies  that  name  should  be  used  as 
the  look-up  name  in  the  profile  database  file.  The  default  is  the  basenameof  the  out- 
put file  (specified  by  the  -o  option.)  This  option  is  incompatible  with  the  +ild 
option. 

Request  a  particular  virtual  memory  page  size  that  should  be  used  for  instructions. 
Seethe  +pd  option  for  additional  information. 

I  ndicates  that  at  run-time,  the  shared  library  loader  can  use  the  environment  variable 
SHLIB_PATH  and  LD_LIBRARY_PATH  (64-bit  only)  to  locate  shared  libraries 
needed  by  the  executable  output  file  that  were  specified  with  either  the  -1  or  -1 : 
option.  The  environment  variables  should  be  set  to  a  colon-separated  list  of  direc- 
tories. If  both  +s  and  +b  are  used,  their  relative  order  on  the  command  line  indi- 
cates which  path  list  will  be  searched  first  (seethe  +b  option). 

This  option  is  ignored  for  32-bit  links.  Turns  on  standard  mode,  which  is  the  default 
in  64-bit  mode.  Options  turned  on  with  this  option  are:  -dynamic.  Options  turned 
off  or  ignored  when  this  option  is  specified  are:  +compat,+noenwar,- 
noshared. 

+vallcompat warnings 

This  option  is  accepted  but  ignored  by  the  64-bit  Id.  Show  more  detail  for  any  warn- 
ings about  compatibility  issues.  By  default,  only  a  terse  message  is  printed.  See  the 
WARNINGS  section  below  for  further  details. 

+v [no] compat warnings 

This  option  is  accepted  but  ignored  by  the  64-bit  Id.  Enable  [disable]  printing  warn- 
ings about  compatibility  issues  between  systems.  This  includes  any  functionality 
which  may  change  in  future  releases.  The  default  is  +vcompat warnings.  See  the 
WARNINGS  section  below  for  further  details. 

+v [no] shlibunsats 

Enable  [disable]  printing  a  list  of  unsatisfied  symbols  used  by  shared  libraries.  The 
default  is  +vnoshlibunsats.  Some  unsatisfied  symbols  reported  by  the  linker  are 
not  required  at  run  time  because  the  modules  which  reference  the  symbols  are  not 
used. 

+FP  flag  Specify  how  the  environment  for  floating-point  operations  should  be  initialized  at  pro- 
gram start-up.  By  default,  all  behaviors  are  disabled.  The  following  flags  are  sup- 
ported (upper  case  flag  enables;  lower  case  flag  disables): 

V  (v)       Trap  on  invalid  floating-point  operations 

Z  (z)       Trap  on  divide  by  zero 


+pd  size 

+pgm  name 

+pi  size 
+s 

+std 
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0  (o)  Trap  on  floating-point  overflow 
U  (u)  Trap  on  floating-point  underflow 

1  (i)  Trap  on  floating-point  operations  that  produce  inexact  results. 

D  (d)  Enable  sudden  underflow  (flush  to  zero)  of  denormalized  values. 

Note:  Enabling  sudden  underflow  is  an  undefined  operation  on  PA-RISC 
1.0-based  systems,  but  it  is  defined  on  all  subsequent  versions  of  PA-RISC. 
Selecting  this  flag  enables  sudden  underflow  only  if  it  is  available  on  the 
processor  being  used  at  run-time. 

To  dynamically  change  these  settings  at  run-time,  seefesettrapenable(3M). 

+1  symbol  Specify  the  name  of  the  initializer  function  when  building  a  shared  library.  A  shared 
library  may  have  multiple  initializers  specified.  I  nitializers  are  executed  in  the  order 
that  they  are  specified.  You  can  specify  more  than  one  initializer,  but  each  must  be 
preceded  by  +1.  For  more  details  on  the  initializer  function,  refer  to  the  +help 
option  or  the  HP-UX  Linker  and  Libraries  User's  Guide  manual. 

+0 [no] f astaccess 

Enable  [disable]  fast  access  to  global  data.  The  linker  rearranges  the  data  to  further 
reduce  the  number  of  ADDIL  instructions  in  the  executable. 

This  optimization  may  reveal  some  subtle  programming  errors  related  to  assumptions 
about  data  layout.  This  optimization  can  occur  at  optimization  levels  2,  3  and  4.  The 
default  is  +Onof astaccess  at  optimization  levels  2  and  3,  and  -i-Of astaccess 
at  optimization  level  4. 

Using  the  -i-Of  astaccess  option  in  the  presence  of  debug  information  generates  a 
warning  message  and  can  cause  corruption  of  the  debug  information.  Avoid  using 
+Of  astaccess  with  the  -g  option. 

This  option  is  accepted  but  ignored  by  the  64-bit  Id. 

+0 [no] procelim 

Enable  [disable]  the  elimination  of  procedures  that  are  not  referenced  by  the  applica- 
tion. The  default  is  +Onoprocelim.  Procedure  elimination  can  occur  at  any  optim- 
ization level,  including  level  0.  For  more  details  refer  to  the  +help  option  or  the 
HP-UX  Linker  and  Libraries  User's  Guide  manual.  This  option  is  incompatible  with 
the  +ild  option. 

+Oreusedir=  di  r 

Specify  the  name  of  the  directory  to  use  as  the  reuse  repository  for  the  object  code 
reuse  feature.  This  directory  holds  the  compiled  object  files  for  reuse,  dir  can  be  an 
absolute  or  relative  path  to  directory  where  you  invoked  the  linker.  The 
-HOreusedir  option  shortens  link  time  by  not  recompiling  intermediate  object  code 
to  object  code  when  using  +04  or  profile-based  optimization. 

-HOselectivepercent  n 

I  nstructs  the  interprocedural  optimizer  driver  to  pass  the  first  n  percent  of  the  object 
files  to  the  high  level  optimizer  for  interprocedural  optimizations  such  as  inlining. 

+Oselectivesize  size 

I  nstructs  the  interprocedural  optimizer  driver  to  pass  the  first  k  routines  to  the  high 
level  optimizer  for  interprocedural  optimization  where  the  size  of  k  routines  are 
approaching  but  less  than  size. 

+Oselective03 

I  nstructs  the  interprocedural  optimizer  driver  to  compile  the  routines  not  included  in 
the  404  list  to  be  compiled  at  -K33. 

-HOstaticprediction 

Meaningful  only  on  PA  2.0  architecture,  this  option  sets  the  branch  prediction  bit  in 
the  output  executable  file's  auxiliary  header. 

32  Bit  Link  Editor  Options 

-A  name  This  option  specifies  incremental  loading.  Linking  is  arranged  so  that  the  resulting 
object  can  be  read  into  an  already  executing  program.  Theargument  name  specifies  a 
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file  whose  symbol  table  provides  the  basisfor  defining  additional  symbols.  Only  newly 
linked  material  isentered  into  the  text  and  data  portions  of  a.  out,  but  the  new  sym- 
bol table  reflects  all  symbols  defined  before  and  after  the  incremental  load.  Also,  the 
-R  option  can  be  used  in  conjunction  with  -A,  which  allows  the  newly  linked  segment 
to  commence  at  the  corresponding  address.  The  default  starting  address  is  the  old 
value  of  _end.  The  -A  option  is  incompatible  with  -r  and  -b.  Also  note  that  a 
program  that  dynamically  loads  code  with  Id  -A  cannot  use  shared  libraries.  See 
the  +help  option  or  the  HP-UX  Linker  and  Libraries  User's  Guide  manual  for  a 
description  of  this  option. 

-Cn  Set  the  maximum  parameter-checking  level  to  n.  The  default  maximum  is  3.  Seethe 

language  manuals  for  the  meanings  of  the  parameter-checking  level. 

-Fl  Force  load  all  member  objects  of  an  archive  library.  If  you  do  not  use  -Fl,  the  linker 

only  loads  the  needed  archive  members.  This  option  is  useful  for  creating  a  shared 
library  from  an  archive  library,  or  when  you  need  to  load  archive  member  that  define 
symbols  needed  by  shared  libraries. 

-Fw  Don't  emit  unwind  tables.  Do  not  use  this  option  if  your  compiler  or  tools  require 

unwind  tables. 

-Fz  Disablethe  linker  feature  that  translates  some  calls  to  $$dyncall_external  to 

calls  to  $$dyncall . 

-N  Generate  an  executable  output  file  with  file  type  EXEC_MAGIC.  This  option  is  incom- 

patible with  -n  and -q.  This  option  causes  the  data  to  be  placed  immediately  follow- 
ing the  text,  and  makes  the  text  writable.  Files  of  thistype  cannot  be  shared. 

-S  Generate  an  Initial  Program  Loader  (I PL)  auxiliary  header  for  the  output  file,  instead 

of  the  default  HP-UX  auxiliary  header. 

-T  Save  the  load  data  and  relocation  information  in  temporary  files  instead  of  in  memory 

during  linking.  Thisoption  reduces  the  virtual  memory  requirements  of  the  linker.  If 
the  TMPDIR  environment  variable  is  set,  the  temporary  files  are  created  in  the 
specified  directory,  rather  than  in  /var/tmp. 

+cdp  oldpath:newpath 

Replace  the  recorded  path  for  a  shared  library  in  the  a. out.  In  32-bit  mode,  Id 
records  the  absolute  path  names  of  any  shared  libraries  searched  at  link  time  in  the 
a. out  file.  When  the  program  begins  execution,  the  dynamic  loader  attaches  any 
shared  libraries  that  were  searched  at  link  time.  Although  you  can  use  the  +b  and/or 
+s  linker  options  to  direct  the  dynamic  loader  to  directories  to  search  for  the  shared 
libraries,  the  dynamic  loader,  as  a  last  resort,  searches  for  the  shared  libraries  in  its 
absolute,  recorded  path  in  the  a. out.  You  can  specify  more  than  one  shared  library 
oldpath:newpath,  but  each  must  be  preceded  by  the+cdp  option. 

+cg  pathname  Specify  the  use  of  pathname  as  the  code  generator  for  compiling  ISOIMs  to  SOMs.  See 
the  discussion  of  profile  based  optimization  in  the  HP-UX  Linker  and  Libraries  Online 
User's  Guidefor  more  information. 

+dpv  Display  verbose  messages  regarding  procedures  which  have  been  removed  due  to  dead 

procedure  elimination.  The  symbol  name,  input  object  file,  and  the  size  (in  bytes)  of 
the  deleted  procedure  are  displayed.  The  total  size  (in  bytes)  of  the  deleted  pro- 
cedures is  also  displayed. 

-Hfilter  shared  l  ibrary  path 

Enables  the  shared  library  filter  mechanism,  which  allows  you  divide  a  large  library 
into  a  "filter"  and  several  "implementation"  libraries  for  more  efficient  organization  of 
shared  libraries,  sharedl  ibrarypath  specifies  the  location  of  the  filter  library.  See 
the  HP-UX  Linker  and  Libraries  User's  Guidefor  more  information. 

-Hgstbuckets  size 

Request  a  particular  number  of  buckets  per  entry  using  the  global  symbol  table  hash 
mechanism.  The  default  value  is  3.  The  value  can  be  overridden  at  runtime  by  set- 
ting the  _HP_DLDOPTS  environment  variable  to  the  value  -symtab_buckets 
number.  You  can  set  the  value  using  chatr  +gstbuckets  sizefile. 

-Hnosmartbind 

Disable  SmartBind  when  binding  a  shared  library.  With  this  option  enabled,  the 
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linker  places  all  symbols  in  the  link  into  a  singleSmartBind  module  instead  of  placing 
each  .  o  file  in  its  own  module. 

+plabel_cache 

Enablethe  plabel  caching  mechanism.  Use  this  option  with  the  +gst  option. 

This  option  is  only  effective  with  C++.  I  n  C++  applications,  the  dynamic  loader  needs 
to  repetitively  access  PLABEL  information  (import  stub).  In  order  to  make  this  access 
faster,  the  dynamic  loader  uses  the  global  symbol  table  structure  to  also  contain  PLA- 
BEL entries.  This  behavior  is  enabled  when  the  PLABEL  CACHE  flag  is  set  in  the 
dl_header  structure  (enabled  Id  +plabel_cache  enable  a.outorchatr 
+plabel_cache  enable  a. out). 

64-bit  Link  Editor  Options 

-k  filename     filename  specifies  a  mapfile  that  describes  the  output  file  memory  map. 

The  user  specified  mapfile  specifications  are  permitted  with  the  +ild  option.  But  you 
should  not  modify  the  mapfile  after  the  initial  incremental  link.  If  the  mapfile  is 
modified  after  the  initial  link,  an  initial  incremental  link  is  performed  automatically. 

Please  refer  to  HP-UX  Linker  and  Libraries  User's  Guide  guide  for  more  information. 
Also  see +nodefaultmap. 

+ [no] allowunsats 

+allowunsats  Does  not  flag  errors  if  the  resulting  output  file  has  unsatisfied  sym- 
bols. This  is  the  default  for  relocatable  links  and  shared  library  builds.  +noal- 
lowunsats  Flags  an  error  if  the  resulting  output  file  has  unsatisfied  symbols.  This 
is  the  default  for  program  files. 

+fini  fundi on  name 

Specify  the  terminator  function. 

+ild  Specify  incremental  linking. 

If  the  output  file  does  not  exist,  or  if  it  was  created  without  the  +ild  option,  the 
linker  performs  an  initial  incremental  link.  The  output  file  produced  is  suitable  for 
subsequent  incremental  links.  The  incremental  link  option  is  valid  for  both  executable 
and  shared  library  links. 

Thefollowing  options  are  compatible  with  the+ild  option  with  limitations: 

-D  offset  ,   -R  offset 

Set  the  origin  for  the  data  and  text  segments.  If  you  change  the  offset  after  the 
initial  incremental  link,  the  linker  performs  an  initial  incremental  link  automati- 
cally. 

-k  mapfile 

provide  a  non-default  mapfile.  The  user  specified  mapfile  specifications  are  per- 
mitted with  the  +ild  option.  But  you  should  not  modify  the  mapfile  after  the 
initial  incremental  link.  If  the  mapfile  is  modified  after  the  initial  link,  an  initial 
incremental  link  is  performed  automatically. 

If  you  specify  one  of  the  following  incompatible  Id  option  with  +ild,  the  linker  emits 
a  warning  message  and  ignores  the  +ild  option. 

-r    create  a  relocatable  object  file. 

Strip  options: 

-s  and  -x  strip  the  output  file.  (The  incremental  linking  requires  the  parts  of 
the  output  load  module  which  are  stripped  out  with  these  options.) 

Optimization  options: 

-I,  -O,  -P,  -PD,  -PF,  +df  file,  +fb,  +fbu,  +fbs,  +pgm  name,  +Opro- 
celim 

+ildnowarn  Suppress  incremental-linking  related  warnings.  By  default,  the  linker  issues  all 
incremental-linking  related  warnings.  This  option  is  ignored  if  used  without  +ild  or 
+ildrelink . 

+ildpad  percentage 

Control  the  amount  of  padding  percentage  the  incremental  linker  allocates,  relative  to 
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sizes  of  object  file  structures  being  padded.  By  default  the  linker  allocates  25%  of  pad- 
ding space.  This  option  is  ignored  if  used  without  +ild  or  +ildrelink. 

+ildrelink  Perform  an  initial  incremental  link,  regardless  of  the  output  load  module. 

I  n  certain  situations  (for  example,  internal  padding  space  is  exhausted)  the  incremen- 
tal linker  is  forced  to  perform  an  initial  incremental  link.  The +ildrelink  option 
allows  you  to  avoid  such  unexpected  initial  incremental  links  by  periodically  rebuild- 
ing the  output  file. 

+init  fundi on  name 

Specify  the  initializer  function. 

+interp  file  Change  the  did  path  to  use  the  argument  as  the  "interpreter"  program  instead  of 
the  did. si. 

+ [no] f orceload 

+forceload  loads  all  object  files  from  archive  libraries.  +noforceload  is  the 
default  —  loads  only  the  required  object  files  from  archive  libraries.  The  mode  that  is 
selected,  either  explicitly  or  by  default,  remains  on  until  it  is  changed. 

+hideall symbols 

This  option  is  used  to  prevent  all  the  symbols  from  being  exported  unless  explicitly 
exported  with  the  +e. 

+nodef aultmap 

This  option  tells  the  linker  not  to  use  the  default  memory  map.  The  user  needs  to 
supply  a  mapfile  through  the  -k  linker  option. 

+nodynhash  Disables  the  default  linker  behavior  of  the  +gst  option  to  create  the  .dynhash  sec- 
tion for  executables  or  shared  libraries.  Use  this  option  to  eliminate  generation  of 
pre-computed  hash  table  information  for  a  library  or  an  executable  that  is  rarely  used 
with  the  global  symbol  table  lookup  scheme  or  for  which  the  overhead  of  storing  pre- 
computed  hash  values  is  too  high.  This  option  has  no  effect  when  used  with  the  -r 
option. 

-Hnoenwar  Instructs  the  dynamic  loader  to  not  look  at  the  LDLI BRARYPATH  and 
SHLIBPATH  environment  variables  at  runtime.  This  is  turned  on  if  Id  +compat 
is  specified.  This  is  turned  off  by  default  or  if  Id  +std  is  specified.  See  +compat 
or  +std.  Generally,  this  option  is  used  for  secure  programs  (e.g.  setuid). 

+nosectionmerge 

Used  with  the  -r  option  to  allow  procedures  to  be  positioned  independently.  The 
default  isto  merge  all  procedures  intoa  single  section. 

-Hpaddata  pagesize 

Pads  the  data  segment  to  a  multiple  of  pagesize  with  zeros.  This  can  improve  page 
allocation,  thus  reduceTLB  misses. 

-Hpadtext  pagesize 

Pads  the  text  segment  to  a  multiple  of  pagesize  with  zeros.  This  can  improve  page 
allocation,  thus  reduceTLB  misses. 

-Hpdzero  Generates  a  zero  page  of  4K  bytes  at  the  beginning  of  the  data  data  segment.  It  also 
sets  the  default  starting  address  of  the  data  segment  to  0x8000000000000000.  This 
option  improves  performance  by  reducing  TLB  misses  by  allowing  the  kernel  to  allo- 
cate bigger  data  pages. 

-Hstripunwind 

Do  not  output  the  unwind  table.  This  creates  smaller  executable  sizes.  Use  this 
option  if  you  do  not  need  the  unwind  table  for  debugging  or  C++ exception  handling. 

+tools         Request  that  the  application  be  linked  for  profiling  with  CXperf. 

+vtype  type  Produces  verbose  output  about  the  link  operation,  typecan  have  the  foil  owing  values: 

files 

Dump  info  about  each  object  file  loaded, 
heap 

Dump  info  about  the  size  of  the  heap  used  by  a  link. 
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libraries 

Dump  infoabout  libraries  searched. 

procelim 

Dump  infoabout  sections  that  have  been  rejected  by  the  +Oprocelim  option 
sections 

Dump  infoabout  each  input  section  added  to  the  output  file, 
symbols 

Dump  infoabout  global  symbols  referenced/defined  from/in  the  input  files, 
all  Dumps  all  of  the  above  info.  Same  as -v. 

Defaults 

Unless  otherwise  directed,  Id  names  its  output  a .  out .  The -o  option  overrides  this.  Executable  output 
files  are  of  type  SHARE_MAGIC .  The  default  state  of  -a  is  to  search  shared  libraries  if  available,  archive 
libraries  otherwise.  Thedefault  bind  behavior  is  deferred. 

Thedefault  value  of  the -Z/-z  option  is-Z. 

For  64-bit  mode,  +std  is  on  by  default. 

Incremental  linking  with  Id  (64-bit  Mode  ONLY) 

In  the  edit-compile-link-debug  development  cycle,  link  time  is  a  significant  component.  The  incremental 
linker  (availablethrough  the  +ild  and  +ildrelink  options)  can  reduce  the  link  time  by  taking  advan- 
tage of  the  fact  that  you  can  reuse  most  of  the  previous  version  of  the  program  and  that  the  unchanged 
object  files  do  not  need  to  be  processed.  The  incremental  linker  allows  you  to  insert  object  code  into  an  out- 
put file  (executable  or  shared  library)  that  you  created  earlier,  without  relinking  the  unmodified  object  files. 
The  time  required  to  relink  after  the  initial  incremental  link  depends  on  the  number  of  modules  you 
modify. 

The  linker  performs  the  foil  owing  different  modes  of  linking: 

•  normal  link:  the  default  operation  mode  in  which  the  linker  links  all  modules. 

•  initial  incremental  link:  the  mode  entered  when  you  request  an  incremental  link,  but  the  output 
module  created  by  the  incremental  linker  does  not  exist,  or  it  exists  but  the  incremental  linker  is 
unableto  perform  an  incremental  update. 

•  incremental  link:  the  mode  entered  when  you  request  an  incremental  link,  an  output  module  created 
by  the  incremental  linker  exists,  and  the  incremental  linker  does  not  require  an  initial  incremental 
link. 

Incremental  links  are  usually  much  faster  than  regular  links.  On  the  initial  link,  the  incremental  linker 
requires  about  the  same  amount  of  time  that  a  normal  link  process  requires,  but  subsequent  incremental 
links  can  be  much  faster  than  a  normal  link.  A  change  in  one  object  file  in  a  moderate  size  link  (tens  of 
files,  several  megabytes  total)  normally  is  about  10  times  faster  than  a  regular  Id  link.  The  incremental 
linker  perform  as  many  incremental  links  as  allocated  padding  space  and  other  constrains  permit.  The  cost 
of  the  reduced  link  time  is  an  increase  in  the  size  of  the  executable  or  shared  library. 

The  incremental  linker  allocates  padding  space  for  all  components  of  the  output  file.  Padding  makes 
modules  larger  than  those  modules  linked  by  Id.  As  object  files  increase  in  size  during  successive  incre- 
mental links,  the  incremental  linker  can  exhaust  the  avail  able  padding.  If  this  occurs,  it  displays  a  warning 
message  and  does  a  complete  initial  incremental  link  of  the  module.  When  an  object  file  changes,  the  incre- 
mental linker  not  only  replaces  the  content  of  that  file  in  the  executable  or  shared  library  being  linked,  but 
also  adjusts  references  to  all  symbols  defined  in  the  object  file  and  referenced  by  other  objects.  This  is  done 
by  looking  at  relocation  records  saved  in  the  incrementally  linked  executableor  shared  library. 

On  the  initial  incremental  link,  the  linker  processes  the  input  object  files  and  libraries  in  the  same  way  as 
the  normal  link.  In  addition  to  the  normal  linking  process,  the  incremental  linker  saves  information  about 
object  files,  global  symbols,  and  relocations,  and  pads  sections  in  the  output  file  for  expansion.  On  subse- 
quent incremental  links,  the  linker  uses  timestamps  and  file  sizes  to  determine  which  object  files  have 
changed,  and  updates  those  modules. 

Under  certain  conditions,  the  incremental  linker  cannot  perform  incremental  links.  When  this  occurs,  the 
incremental  linker  automatically  performs  an  initial  incremental  link  to  restore  the  process.  In  the  follow- 
ing situations,  the  linker  automatically  performs  an  initial  incremental  link  of  the  output  file: 
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•  Changed  linker  command  line,  where  the  linker  command  line  does  not  match  the  command  line 
stored  in  the  output  file.  (With  the  exceptions  of  the  verbose  and  tracing  options) 

•  Any  of  the  padding  spaces  have  been  exhausted. 

•  Modules  have  been  modified  by  the  Id  -s  or  Id  -x  options  or  tools  (for  example,  strip(l)).  The 
incremental  linking  requires  the  parts  of  the  output  load  module  which  are  stripped  out  with  these 
options. 

•  I  ncompatible  incremental  linker  version,  when  you  run  a  new  version  of  the  incremental  linker  on  an 
executable  created  by  an  older  version. 

•  New  working  directory,  where  the  incremental  linker  performs  an  initial  incremental  link  if  current 
directory  changes. 

•  Archive  or  shared  librariesare  added/removed  to/from  thelinker  command  line. 

•  Objects  are  added/removed  to/from  the  linker  command  line. 

Seethe  Online  Linker  and  Libraries  User's  Guide  (Id  +help)  for  more  information. 
Archive  Library  Processing 

The  incremental  linker  searches  an  archive  library  if  there  are  unsatisfied  symbols.  It  extracts  all  archive 
members  satisfying  unsats  and  processes  them  as  new  object  files.  If  an  archive  library  is  modified,  the 
linker  replaces  the  modifed  archive  library. 

An  object  file  extracted  from  an  archive  library  in  the  previous  link  remains  in  the  output  load  module  even 
if  all  references  to  symbols  defined  in  the  object  file  have  been  removed.  The  linker  removes  these  object 
files  when  it  performs  the  next  initial  incremental  link. 

Shared  Library  Processing 

In  an  initial  incremental  link,  the  linker  scans  shared  library  symbol  tables  and  resolves  unsats  the  same 
way  it  would  in  a  regular  link.  I  n  incremental  links,  the  linker  does  not  process  shared  libraries  and  their 
symbol  tables  at  all  and  does  not  report  shared  library  unsats.  The  dynamic  loader  detects  them  at  run 
time.  If  any  of  the  shared  libraries  on  the  command  line  was  modified,  the  linker  reverts  to  an  initial  incre- 
mental link. 

Performance 

Performance  of  the  incremental  linker  may  suffer  greatly  if  you  change  a  high  percentage  of  object  files. 

The  incremental  linker  may  not  link  small  programs  much  faster,  and  the  relative  increase  in  size  of  the 
executable  is  greater  than  that  for  larger  programs. 

Generally,  the  linker  needs  to  scan  through  all  shared  libraries  on  a  link  line  in  order  to  determine  all  the 
unsats,  even  in  incremental  links.  This  process  may  slow  down  incremental  links.  The  incremental  linker 
does  not  scan  shared  librariesand  leaves  detection  of  shared  library  unsats  to  the  dynamic  loader. 

Do  not  use  the  incremental  linker  to  create  final  production  modules.  Because  it  reserves  additional  pad- 
ding space,  modules  created  by  the  i ncremental  linker  are  considerably  larger  than  those  created  in  regular 
links. 

Notes 

Any  program  that  modifies  an  executable  (for  example,  strip(l)),  may  affect  the  ability  of  Id  to  perform 
an  incremental  link.  When  this  happens,  the  incremental  linker  issues  a  message  and  performs  an  initial 
incremental  link. 

Third-party  tools  that  work  on  object  files  may  have  unexpected  results  on  modules  produced  by  the  incre- 
mental linker. 

EXTERNAL  INFLUENCES 
Environment  Variables 

The  following  internationalization  variables  affect  the  execution  of  Id: 

FLOW_DATA 

An  instrumented  executable  (see  the  -I  option)  writes  out  the  profile  data  to  a  database  file  named 
flow. data  in  the  current  directory.  The  name  and  location  of  this  file  can  be  specified  by  setting 
FLOWDATA  to  the  desired  path  name.  The  profile  data  is  stored  in  the  database  file  under  a  look-up 
name  that  is  the  same  as  the  basenameof  the  executable  file  specified  at  run-time.  A  single  flow. data 
filecan  hold  profiledata  for  multiple  program  files. 


HP-UX  Release  Hi:  December  2000 


-13- 


Section  1-435 


IdU) 


ld(l) 


LANG 

Determines  the  locale  category  for  native  language,  local  customs  and  coded  character  set  in  the 
absenceof  LC_ALL  and  other  LC_*  environment  variables.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of  LANG. 

LC_ALL 

Determines  the  values  for  all  locale  categories  and  has  precedence  over  LANG  and  other  LC_* 
environment  variables. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic  messages 
written  to  standard  error. 

LC_NUMERIC 

Determines  the  locale  category  for  numeric  formatting. 

LC_CTYPE 

Determines  the  locale  category  for  character  handlingfunctions. 

NLSPATH 

Determines  the  location  of  message  catalogs  for  the  processing  of  LC_ME S SAGE S  . 

If  any  internationalization  variable  contains  an  invalid  setting,  Id  behaves  as  if  all  internationalization 
variables  are  set  toe.  See  environ  (5). 

I  n  addition,  the  foil  owing  environment  variable  affects  Id: 

TMPDIR 

Specifies  a  directory  for  temporary  files  (see  tmpnam(3S)). 
DIAGNOSTICS 

Id  returns  zero  when  the  link  is  successful.  A  non-zero  return  code  indicates  that  an  error  occurred. 
EXAMPLES 

Link  part  of  a  C  program  for  later  processing  by  Id.  (Note  the  .  o  suffix  for  the  output  object  file;  this  is 
an  HP-UX  convention  for  indicatinga  linkableobject  file): 

Id  -r  filel.o  file2.o  -o  prog.o 

On  32-bit,  link  a  simple  Fortran  program  for  use  with  the  dde  symbolic  debugger  (see  dde(l)).  Output 
file  name  is  a.  out  si  nee  there  is  no  -o  option  in  the  command  line. 

Id  /usr/ccs/lib/crtO . o  ftn.o  -lcl  -lisamstub  \ 
-lc  /opt/langtools/lib/end. o 

To  do  this  on  64-bit: 

Id  ftn.o  -lcl  -lisamstub  \ 

-lc  /opt/langtools/lib/pa20_64/end. o 

On  64-bit,  link  a  shared  bound  program  in  standard  mode.  Note  that  crtO  .o  is  not  specified  because  for 
shared  links,  it  is  no  longer  necessary. 

Id  himom.o  +std  -lc 

On  64-bit,  link  a  compatibility  mode  program.    crtO  .  o  is  included  because  this  is  an  archive  link. 

Id  /opt/langtools/lib/pa20_64/crt0 . o  himom.o  -Hcompat  -a  archive  -lc 
Create  a  shared  library: 

Id  -b  -o  libf unc . si   f unci . o  f unc2 . o  f unc3 . o 

Create  a  shared  library  with  an  internal  name: 

Id  -b  -o  libf ool . 1  fool . o  f oo2 . o  +h  libf ool . 1 

In  -s  libf ool . 1  libf ool . si 

cc  -g  mytest . c  -L .   -If ool 

chatr  a . out 

shared  library  list: 
dynamic  ./libfool.l 
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If  you  do  not  use  +h,  the  shared  library  does  not  have  an  internal  name.  The  linker  does  not  check 
whether  .si  is  a  symbolic  link.  It  records  the  library  name  that  it  looks  at,  if  it  does  not  have  the  internal 
name. 

chatr  a . out 

shared  library  list: 
dynamic  ./libfool.sl 

On  32-bit,  link  a  program  with  libfunc.sl  but  use  the  archive  version  of  the  C  library.  Specify  the 
immediate  binding  mode  together  with  the  nonfatal  modifier  and  allow  verbose  diagnostics  to  be  displayed: 

Id  /usr/ccs/lib/crtO . o  -B  immediate  -B  nonfatal  -B  verbose  \ 
program. o  -L       -lfunc  -a  archive  -lc 

To  do  this  on  64-bit: 

Id  -B  immediate  -B  nonfatal  -B  verbose  \ 
program. o  -L       -lfunc  -a  archive  -lc 

On  32-bit,  link  a  Pascal  program: 

Id  /usr/ccs/lib/crtO . o  main.o  -lcl  -lm  -lc 

Note  that  in  the  above  examples,  /usr/ccs/lib/crtO .  o  can  be  replaced  by 
/opt/langtools/lib/crtO . o. 

WARNINGS 

Id  recognizes  several  names  as  having  special  meanings.  The  symbol  _end  is  reserved  by  the  linker  to 
refer  to  the  first  address  beyond  the  end  of  the  program's  address  space.  Similarly,  the  symbol  _edata 
refers  to  the  first  address  beyond  the  initialized  data,  and  the  symbol  _etext  refers  to  the  first  address 
beyond  the  program  text.  The  symbols  end,  edata,  and  etext  are  also  defined  bythelinker,  but  only  if 
the  program  contains  a  reference  to  these  symbols  and  does  not  define  them  (see  end(3C)  for  details).  On 

32-bit,  the  symbol   tdsize  is  the  total  thread  local  storage  size  required  by  the  program  or  shared 

library. 

On  64-bit,  the  linker  defines  a  few  more  symbols.  The  symbol   TLS_SIZE  is  the  total  thread  local 

storage  size.  The  symbol  _FPU_STATUS  is  the  initial  status  of  the  FPU  status  register.  The  symbol 
 SYSTEM_ID  is  the  largest  architecture  revision  level  used  by  any  compilation  unit. 

The  linker  treats  a  user  definition  of  any  of  the  symbols  listed  here  as  an  error. 

Through  its  options,  the  link  editor  gives  users  great  flexibility.  However,  those  who  invoke  the  linker 
directly  must  assume  some  added  responsibilities.  I  nput  options  should  ensure  the  following  properties  for 
programs: 

•  When  the  link  editor  is  called  through  cc(l),  a  start-up  routine  is  linked  with  the  user's  program. 
This  routine  calls  exit(2)  after  execution  of  the  main  program.  If  users  call  Id  directly,  they  must 
ensure  that  the  program  always  calls  exit  ()  rather  than  falling  through  the  end  of  the  entry 
routine. 

•  When  I  inking  for  use  with  the  symbolic  debugger  dde,  the  user  must  ensure  that  the  program  con- 
tains a  routine  called  main.  Also,  the  user  must  link  in  the  file 
/opt/langtools/lib/end.  o  on  32-bit  and  /opt/langtools/lib/pa20_64/end.  o 
on  64-bit  as  the  last  file  named  on  the  command  line. 

There  is  no  guarantee  that  the  linker  will  pick  up  files  from  archive  libraries  and  include  them  in  the  final 
program  in  the  same  relative  order  that  they  occur  within  the  library. 

The  linker  emits  warnings  where  ever  it  detects  any  compatibility  issues.  Among  other  things,  these  issues 
include  architectural  ones,  as  well  as  functionality  that  may  changeover  time.  Some  of  these  include: 

•  Linking  a  PA  2.0  object  file,  which  will  not  run  on  a  PA  1.x  system. 

•  Incremental  loading  with  the  -A  option. 

•  Procedure  call  parameter  and  return  type  checki ng,  includingthe  -C  option. 

•  Symbols  with  the  same  name  but  different  types,  such  as  CODE  and  DATA. 

•  Checking  of  unsatisfied  symbols  by  the  linker,  which  sometimes  skips  certain  object  files  from  an 
archived  library.  This  warning  is  only  given  if  the  -v  option  is  also  provided. 
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•  Versioning  of  objects  within  a  shared  library. 
These  messages  can  be  turned  off  with  the  +vnocompatwarnings  option. 
As  noted  in  the  Options  section,  certain  options  no  longer  exist  in  a  64-bit  linker.  They  are: 

-q 

—A 
-C 
-E 

-Q 

-s 

-T 
-X 

+dpv 

Some  restrictions  exist  for  64-bit  mode  with  executables  built  with  shared  libraries  and  with  S-bit  set 
(through  +s  enabled).  The  behavior  of  64-bit  executables  does  not  match  the  behavior  of  equivalent  32-bit 
executables  or  executables  built  with  +compat.  For  any  setuid  or  setgid  programs,  did  disables  any 
dynamic  library  searching  through  environment  variables,  SHLIB_PATH  for  32-bit  and  64-bit  mode,  and 
LD_LIBRARY_PATH  for  64-bit  mode.  If  a  library  only  exists  in  the  directory  specified  in  SHLIB_PATH 
(or  LD_LIBRARY_PATH),  you  get  the  runtime  error  "library  not  found"  if  the  program  is  a  setuid  program 
(that  is,  uid  not  equal  to  euid  or  gid  not  equal  to  eguid)  and  it  depends  on  that  library,  did  uses  the 
dynamic  path  lookup  (with  SHLIB_PATH)  only  if  the  following  conditions  are  satisfied:  getuid  () 
==  geteuid  ()  &&  getgid  ()  ==  getegid  ().  That  is,  if  the  uid  or  gid  does  not  match  its 
effective  counterpart,  did  searches  only  the  recorded  library  path.  As  a  result,  did  does  not  check  the 
SHLIB_PATH  which  causes  the  runtime  error  "library  not  found". 

AUTHOR 

Id  was  developed  by  AT&T,  the  University  of  California,  Berkeley,  and  HP. 
FILES 

/usr/lib/lib*  32-bit  system  archive  and  shared  libraries 

/usr/lib/pa20_64/lib*  64-bit  system  archive  and  shared  libraries 

/usr/ccs/lib*  32-bit  development  archive  and  shared  libraries 

/opt/langtools/lib/pa20_64  64-bit  development  object  files,  archive  and  shared  libraries 

a. out  output  file 

/usr/lib/dld .  si  32-bit  dynamic  loader 

/usr/lib/pa20_64/dld.  si  64-bit  dynamic  loader 

/opt/langtools/lib/end .  o  for  use  with  the  32-bit  dde  debugger 

/opt/langtools/lib/pa20_64/end. o 

for  use  with  the  64-bit  dde  debugger 

/usr/ccs/lib/crtO  .  o  32-bit  run-time  startup  file 

/opt/langtools/lib/crtO.o        Identical  to  /usr/ccs/lib/crtO  .  o 

/opt/langtools/lib/pa20_64/crt0 . o 

64-bit  run-time  startup  file 

/usr/ccs/lib/dyncall .  o  32-bitonly.  Used  with  -A  option  links 

/opt/langtools/lib/mcrtO  .  o      32-bit  run-time  startup  with  profiling  (see  prof(l)) 

/opt/langtools/lib/pa20_64/mcrt0 . o 

64-bit  run-time  startup  with  profiling 

/usr/lib/milli  .  a  32-bit  millicode  library  automatically  searched  by  Id 

/usr/lib/pa20_64/milli  .  a         64-bit  millicode  library  automatically  searched  by  Id 
/opt/langtools/lib/gcrtO  .  o      run-time  start-up  with  profiling  (see  gprof (1)) 

/opt/langtools/lib/pa20_64/gcrt0 . o 

64-bit  run-time  start-up  with  profiling  (see  gprof (1)) 
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/opt/langtools/lib/icrtO  .o      32-bit  run-time  start-up  with  profiling  (see  discussion  of  profile 

based  optimization  above.) 

/opt/langtools/lib/pa20_64/icrt0 . o 

64-bit  run-time  start-up  with  profiling  (see  discussion  of  profile 
based  optimization  above.) 

message  catalog 

temporary  files 

file  containing  profile  data  generated  by  running  an  instru- 
mented executable 

program  for  creating  the  procedure  link  order  from  a  profile 
database  file  created  by  an  instrumented  executable;  forked  by 
the  -P  option 


/usr/lib/nls/$LANG/ld. cat 

/var/tmp/ld* 

flow. data 

/usr/ccs/bin/ fdp 


/opt/langtools/lbin/ucomp        PA-RISC  code  generator 


SEE  ALSO 

Profiling  and  Debugging  Tools: 

adb(l)  absolute  debugger 

gprof(l)  display  call  graph  profile  data 

prof(l)  display  profile  data 

dde(l)  C,  C++,  FORTRAN,  and  Pascal  symbolic  debugger 


System  Tools: 

aCC(l)  invoke  the  HP-UX  aC++compiler 

ar(l)  create  archived  libraries 

CC(1)  invoke  the  HP-UX  C++compiler 

cc(l)  invokethe  HP-UX  C  compiler 

chatr(l)  change  program's  internal  attributes 

exec(2)  execute  a  file 

f77(l)  invokethe  HP-UX  FORTRAN  77  compiler 

f90(l)  invokethe  HP-UX  Fortran  90compiler 

fastbind(l)  invoke  the  fastbind  tool 

nm(l)  print  name  list  of  object  file 

pc(l)  invokethe  HP-UX  Pascal  compiler 

strip(l)  strip  symbol  and  line  number  information  from  an  object  file 

Miscellaneous: 

a.out(4)  assembler,  compiler,  and  linker  output 

ar(4)  archive  format 

crt0(3)  execution  startup  routine 

did. si  (5)  dynamic  loader 

end(3C)  symbol  of  the  last  locations  in  program 


Texts  and  Tutorials: 

HP-UX  Linker  and  Libraries  Online  User  Guide 

(Seethe+help  option) 
HP-UX  Linker  and  Libraries  User's  Guide 

(See  manuals(5)  for  ordering  information) 


STANDARDS  CONFORMANCE 

Id:  SVI D2,  SVI D3,  XPG2,  XPG4 
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NAME 

Idd  -  list  dynamic  dependencies  of  executable  files  or  shared  libraries 

SYNOPSIS 

ldd  [-b]  [-d]  [-r]  [-s]  [-v]  filename... 

DESCRIPTION 

ldd  is  a  command  that  can  list  the  dynamic  dependencies  of  incomplete  executable  files  or  shared  libraries. 

ldd  lists  verbose  information  about  dynamic  dependencies  and  symbol  references.  If  the  object  file  is  an 
executable  file,  ldd  lists  all  shared  libraries  that  would  be  loaded  as  a  result  of  executing  the  file.  If  it  is  a 
shared  library,  ldd  lists  all  shared  libraries  that  would  be  loaded  as  a  result  of  loading  the  library. 

ldd  uses  the  same  algorithm  as  the  dynamic  loader  (/usr/lib/dld.  si  and 
/usr/lib/pa20_64/dld.  si)  to  locate  the  shared  libraries  at  runtime.  See  "Dynamic  Path  List"  in 
dld.sl  (5)  for  more  information. 

Options 

ldd  recognizes  the  following  options: 

-b  PA32-only.  Used  in  conjunction  with  -d  and/or  -r  to  force  dld.sl  to  bind  all  dependent 
libraries  and  report  unsats.  By  default,  the  smartbind  mechanism  in  dld.sl  only  binds 
libraries  whose  symbols  are  explicitly  referenced. 

-d  Check  reference  to  data  symbols. 

-r  Check  reference  to  data  and  code  symbols. 

-s  Display  the  search  path  used  to  locate  the  shared  libraries. 

-v  Display  all  dependency  relationships. 

EXTERNAL  INFLUENCES 
Environment  Variables 

ldd  uses  the  foil  owing  environment  variables  to  locate  shared  libraries. 

LD_LIBRARY_PATH 

64-bit  mode  A  colon-separated  list  of  path  names  which  defines  the  search  path  for  shared  libraries  at 
runtime.  See  "Dynamic  Path  List"  in  dld.sl  (5)  for  more  information. 

SHLIB_PATH 

A  colon-separated  list  of  path  names  which  defines  the  search  path  for  shared  libraries  at  runtime. 
See  "Dynamic  Path  List"  in  dld.sl  (5)  for  more  information. 

Thefollowing  internationalization  variables  affect  the  execution  of  ldd: 

LANG 

Determines  the  locale  category  for  native  language,  local  customs  and  coded  character  set  in  the 
absence  of  LC_ALL  and  other  LC_*  environment  variables.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of  LANG. 

LC_ALL 

Determines  the  values  for  all  locale  categories  and  has  precedence  over  LANG  and  other  LC_* 
environment  variables. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic  messages 
written  to  standard  error. 

LC_NUMERIC 

Determines  the  locale  category  for  numeric  formatting. 

LC_CTYPE 

Determines  the  locale  category  for  character  handlingfunctions. 

NLSPATH 

Determines  the  location  of  message  catalogs  for  the  processing  of  LC_ME S SAGE S  . 

If  any  internationalization  variable  contains  an  invalid  setting,  ldd  behaves  as  if  all  internationalization 
variables  are  set  toe.  See  environ  (5). 
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DIAGNOSTICS 

ldd  prints  the  record  of  shared  library  path  names  to  stdout.  The  optional  list  of  symbol  resolution  prob- 
lems are  printed  to  stderr. 

ldd  returns  zero  when  the  operation  is  successful.  A  non-zero  return  code  indicates  that  an  error 
occurred. 


EXAMPLES 

By  default  ldd  prints  a  simple  dynamic  path  information.  This  consists  of  the  dependencies  recorded  in  the 
executable  (or  the  shared  library)  followed  by  the  physical  location  where  these  libraries  are  found. 

ldd  a . out 

./libx.sl  =>  ./libx.sl 

libc.2  =>  /lib/pa20_64/libc.2 

libdl.l  =>  /lib/pa20_64/libdl.l 

The-v  option  causes  ldd  to  print  dependency  relationship  along  with  the  dynamic  path  information. 

ldd  -v  a . out 

find  library= . /libx . si;    required  by  a. out 

./libx.sl  =>  ./libx.sl 
find  library=libc . 2 ;    required  by  a. out 

libc.2  =>  /lib/pa20_64/libc.2 
find  library=libdl . 1;    required  by  /lib/pa20_64/libc . 2 

libdl.l  =>  /lib/pa20_64 /libdl.l 

The  -r  option  to  ldd  causes  it  to  analyze  all  symbol  references  and  print  information  about  unsatisfied 
code  and  data  symbols. 

ldd  -r  a . out 

./libx.sl  =>  ./libx.sl 
libc.2  =>  /lib/pa20_64/libc.2 
libdl.l  =>  /lib/pa20_64/libdl . 1 

symbol  not  found:   vail  (./libx.sl) 
symbol  not  found:    count  (./libx.sl) 
symbol  not  found:    funcl  (./libx.sl) 

WARNINGS 

ldd  does  not  list  shared  libraries  explicitly  loaded  using  dlopen(3C)  or  shl_load(3X). 
FILES 

a.  out  output  file 

/usr/lib/dld .  si  32-bit  PARI  SC  dynamic  loader 

/usr/lib/pa20_64/dld.sl  64-bit  PARI  SC  dynamic  loader 

/usr/ccs/lib/lddstub  32-bit  dummy  executable  loaded  to  check  the  dependencies 

of  shared  libraries 

/usr/ccs/lib/pa20_64/lddstub        64-bit  dummy  executable  loaded  to  check  the  dependencies 

of  shared  libraries 
/usr/lib/nls/$LANG/ldd .  cat  message  catalog 


SEE  ALSO 

System  Tools: 

I d (1)  invoke  the  link  editor 

Miscellaneous: 

a.out(4)  assembler,  compiler,  and  linker  output 

did. si  (5)  dynamic  loader 

Texts  and  Tutorials: 

HP-UX  Linker  and  Libraries  User's  Guide 
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NAME 

leave  -  remind  you  when  you  have  to  leave 

SYNOPSIS 

leave  [hhmm] 

DESCRIPTION 

The  leave  command  waits  until  the  specified  time,  then  reminds  you  to  leave.  You  are  reminded  5 
minutes  and  1  minute  before  the  actual  time,  at  the  time,  and  every  minute  thereafter.  When  you  log  off, 
leave  exits. 

The  time  of  day  is  in  the  form  hhmm,  where  hh  is  a  time  in  hours  (which  can  range  from  0  through  11  or  0 
through  24  hours),  and  mm  is  the  number  of  minutes  after  the  specified  hour.  If  the  value  of  hh  is  greater 
than  11  (24-hour  clock  time),  the  specified  value  is  reduced  by  12  to  a  new  value  in  the  range  of  0  through 
11,  thus  ensuring  that  the  alarm  time  is  always  set  to  activate  within  the  next  12  hours.  For  example,  if 
hhmm  is  1350  and  the  current  time  is  4:00  PM  (1600),  the  1350  value  is  changed  to  150  and  the  alarm  is  set 
for  1:50  AM,  nine  hours  and  50  minutes  later.  On  the  other  hand,  if  it  is  9:00  AM  and  hhmm  is  specified  as 
2200  (10:00  PM),  the  value  used  is  converted  to  1000  and  the  alarm  is  set  for  one  hour  later  instead  of  13 
hours  as  specified. 

If  no  argument  is  provided,  leave  prompts  with 

When  do  you  have  to  leave? 

A  reply  of  newline  causes  leave  to  exit;  otherwise  the  reply  is  assumed  to  be  a  time.  This  form  is  suitable 
for  inclusion  in  a  .login  or  .profile  file. 

The  leave  command  ignores  interrupts,  quits,  and  terminate  signals.  To  get  rid  of  it  you  should  either  log 
off  or  use  kill  -9  giving  its  process  I D. 

EXAMPLES 

The  command 

leave  1204 

sends  an  alarm  (a  beep)  to  your  terminal  to  remind  you  that  you  have  to  leave  at  12:04  and  reminds  you 
that  you  are  I  ate  at  one  minute  intervals  after  12:04. 

WARNINGS 

The  leave  command  checks  to  see  if  a  user  has  logged  out  by  checking  the  /etc/utmp  file  every  100 
seconds.  If  a  user  logs  out  and  logs  back  in  to  the  same  tty  before  leave  makes  its  periodic  check,  leave 
may  not  know  that  the  user  has  logged  out. 

AUTHOR 

leave  was  developed  by  the  University  of  California,  Berkeley. 

FILES 

/etc/utmp 

SEE  ALSO 

calendar(l). 
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NAME 

lifcp  -  copy  to  or  from  LIF  files 
SYNOPSIS 

lifcp  [-Txxx]  [-Lxxx]  [ -vxxx ]  [-a]  [-b]  [-i  xxx]  [-r]  [-t]  filel  file2 

lifcp  [-Txxx]  [-Lxxx]  [-vxxx]  [-a]  [-b]  [-ixxx]  [-r]  [-t]  [filel  file2  ...]  directory 

DESCRIPTION 

lifcp  copies  a  LIF  file  to  an  HP-UX  file,  an  HP-UX  file  to  a  LIF  file,  or  a  LIF  file  to  another  LIF  file.  It  also 
copies  a  list  of  (HP-UX/LIF)  files  to  a  (LIF/HP-UX)  directory.  The  last  name  on  the  argument  list  is  the 
destination  file  or  directory. 

Options  can  be  used  singly  or  combined  in  any  order  before  the  file  names.  The  space  between  option  and 
argument  is  optional. 

-Txxx  Used  only  when  copying  files  to  a  LIF  volume.  This  option  forces  the  file  type  of  the  LIF 
directory  entry  to  be  set  to  the  argument  given.  The  argument  can  be  decimal,  octal  or 
hex,  using  standard  "C"  notation. 

-Lxxx  Used  only  when  copying  files  to  a  LI  F  volume.  This  option  will  set  the  "last  volume  flag" 
to  xxx  (0  or  1).  The  default  "last  volume  flag"  is  1. 

-vxxx  Used  only  when  copying  files  to  a  LIF  volume.  This  option  sets  the  "volume  number"  to 
xxx.  The  default  "volume  number"  is  one. 

-a  This  option  forces  a  ASCI  I  mode  of  copying  regardless  of  the  file  type.  When  copying  in 

ASCII  mode  from  HP-UX  to  LIF  the  default  file  type  is  BINARY  (1).  (For  details  on 
available  modes  of  copying  refer  to  lif(4)).  This  option  has  no  effect  when  copying  from 
LIF  to  LI F. 

-b  This  option  forces  a  Bl  NARY  mode  of  copying  regardless  of  the  file  type.  When  copying 

in  BINARY  mode  from  HP-UX  to  LIF  the  default  filetype  is  BINARY  (-2).  (For  details 
on  avail  able  modes  of  copying  refer  to  I  if  (4)).  This  option  has  no  effect  when  copying  from 
LIF  to  LI F. 

-ixxx  Used  only  when  copying  files  to  a  LI  F  volume.  This  option  sets  the  "implementation"  field 

of  the  LIF  directory  entry  to  the  argument  given.  The  argument  value  can  be  decimal, 
octal  or  hex,  using  standard  "C"  notation.  The  "implementation"  field  can  only  be  set  for 
file  types  -2001  to  -100000  (octal).  The  "implementation"  field  is  set  to  zero  for  all  inter- 
change file  types  and  for  file  types  -2  to  -200  (octal).  Note  that  the  "implementation" 
value  controls  the  attributes  of  the  LIF  file  with  regard  to  protection  and  record  sizes, 
lifls  -I  or  lifls  -i  can  be  used  to  determine  the  "implementation"  value  of  a  file. 

-r  Forces  RAW  mode  copying  regardless  of  file  type.  When  copying  in  RAW  mode  from  HP- 

UX  to  LI  F  the  default  file  type  is  Bl  N  (-23951).  -T  option  overrides  the  default  file  type, 
(various  modes  of  copying  are  explained  in  lif(4).)  -r  option  has  no  effect  in  LIF  to  LIF 
copy  operations. 

-t  causes  HP-UX  file  names  to  be  translated  to  a  name  acceptable  by  a  LIF  utility;  that  is, 

all  lowercase  letters  are  converted  to  uppercase  and  all  other  characters  except  numerics 
are  changed  to  an  underscore  (_).  If  the  HP-UX  file  name  starts  with  a  nonletter,  the  file 
name  is  preceded  by  the  capital  letter  X.  Thus,  for  example,  if  two  files  named  colon  (:) 
and  semicolon  (;),  were  copied,  both  of  them  would  be  translated  to  X_.  File  names  are 
truncated  to  a  maximum  of  10  characters.  When  copying  a  LIF  file  to  an  HP-UX  or  LI F 
file,  -t  has  no  effect.  Omitting  -t  causes  an  error  to  be  generated  if  an  improper  name  is 
used. 
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The  default  copying  modes  when  copying  from  LI  F  to  HP-UX  are  summarized  in  the  foil  owing  table: 


File  Type 

Default  Copying  Mode 

ASCII 

ASCII 

BINARY 

BINARY 

BIN 

RAW 

other 

RAW 

When  copying  from  HP-UX  to  LI  F,  the  default  copying  mode  is  ASCI  I  and  an  ASCI  I  file  is  created. 

When  copying  from  LI  F  to  LI  F,  if  no  options  are  specified,  then  all  the  LI  F  directory  fields  and  file  contents 
are  duplicated  from  source  to  destination. 

A  LIF  file  name  is  recognized  by  the  embedded  colon  (:)  delimiter  (see  lif(4)  for  LIF  file  naming  conven- 
tions). A  LI  F  directory  is  recognized  by  a  trailing  colon.  If  an  HP-UX  file  name  containing  a  colon  is  used, 
the  colon  must  be  escaped  with  two  backslash  characters  (\\ )  (the  shell  removes  one  of  them). 

Thefile  name-  (dash)  is  interpreted  to  mean  standard  input  or  standard  output,  depending  on  its  position 
in  the  argument  list.  This  is  particularly  useful  if  the  data  requires  nonstandard  translation.  When  copy- 
ing from  standard  input,  if  no  other  name  can  be  found,  the  name  "STDI N"  is  used. 

LIF  file  naming  conventions  are  known  only  to  the  LI  F  utilities.  Since  file  name  expansion  is  done  by  the 
shell,  this  mechanism  cannot  be  used  for  expanding  LIF  file  names. 

Do  not  mount  the  special  file  while  using  lifcp. 
DIAGNOSTICS 

lifcp  returns  exit  code  0  if  the  file  is  copied  successfully.  Otherwise  it  prints  a  diagnostic  and  returns 
nonzero. 

EXAMPLES 

Copy  HP-UX  fileabc  to  LIF  file  CDE  on  LIF  volume  lifvol  which  is  actually  an  HP-UX  file  initialized  to  be 
a  LI  F  volume: 

lifcp  abc  lifvol :CDE 

Copy  all  the  HP-UX  files  in  the  current  directory  to  the  LIF  volume  lifvol  which  is  present  in  the  parent 
directory.  FilenamesaretranslatedtoappropriateLIF  filenames. 

lifcp  -t  *  ../lifvol: 

Copy  all  the  HP-UX  object  files  in  the  current  directory  to  the  LIF  volume  lifvol .  Copying  mode  is  RAW 
and  LIF  file  types  are  set  to -5555. 

lifcp  -r  -T  -5555  -t  *.o  lifvol: 

Copy  all  the  object  files  in  the  current  directory  to  the  LIF  volume  lifvol.  Copying  mode  is  Bl NARY  and 
LIF  Bl  NARY  files  are  created. 

lifcp  -r  -T  0xffffe961  -i  0x20200080  bdat  MfvohBDAT 

Copy  a  BDAT  file,  without  a  password,  from  a  BASIC  Workstation  to  an  HP-UX  LIF  volume  lifvol.  Note 
that  -i  controls  protection  and  record  size  attributes.  The  file  type  for  a  BDAT  file  is  -5791  (or  0xffffe961) 
and  its  record  size  is  256  bytes  per  record. 

lifcp  -b  *.o  lifvol: 

Copy  all  files  in  the  current  directory  to  the  LIF  volume  lifvol  in  the  root  directory.  Copying  mode  is  RAW 
and  LIF  file  types  are  set  to  Bl  N. 

lifcp  -r  -t  *  /lifvol: 
Copy  file  abc:  to  LIF  file  CDE  in  lifvol. 

lifcp  abc\\:  lifvol :CDE 
Copy  files  abc  and  def  to  LIF  files  ABC  and  DEF  within  lifvol. 

lifcp  -t  abc  def  lifvol: 
Copy  LIF  fileABC  within  lifvol  tofileABC  within  current  directory. 
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lifcp  MfvohABC  . 

Copy  standard  input  to  LI  F  fileA_FILE  on  LIF  volume/dev/dsk/c0t6d0. 

lifcp  -  /dev/dsk/cOt6dO:A_F  I L  E 
CopyLIF  fileABC  inlifvol  toLIF  fileCDE  on /dev/dsk/cOt6dO . 

lifcp  MfvohABC  /dev/dsk/cOt6dO:CDE 
Copy  the  output  of  pr  to  the  LIF  fileABC. 

pr  abc  |  lifcp  -  MfvohABC 

Copy  the  output  of  pr  to  the  LIF  volume  lifvol.  LIF  file  STDIN  is  created  since  no  files  names  are 
specified. 

pr  abc  |  lifcp  -  lifvol: 

CopyLIF  fileABC  inlifvol  to  standard  output, 
lifcp  lifvol  ABC  - 

Copy  all  files  in  current  directory  to  LIF  files  of  the  same  name  on  LIF  volume  lifvol  (may  cause  errors  if 
file  names  in  the  current  directory  do  not  obey  LIF  naming  conventions!). 

lifcp  *  ../lifvol: 

DEPENDENCIES 

Series  700/800 

T  h  e  f  ol  I  owi  ng  opt  i  on  i  s  a  I  so  su  pported : 

-Knnn  forces  each  file  copied  in  to  begin  on  a  nnn  x  1024-byte  boundary  from  the  begin- 

ning of  the  volume.  This  is  useful  when  files  are  used  for  Series  700/800  boot 
media.  This  option  has  no  effect  when  copying  from  a  LIF  volume. 

AUTHOR 

lifcp  was  developed  by  the  Hewlett-Packard  Company. 

SEE  ALSO 

lifinit(l),  lifls(l),  lifrename(l),  lifrm(l),  lif(4). 
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NAME 

lifinit  -  write  LI  F  volume  header  on  file 
SYNOPSIS 

lifinit  [-vnnn]  [-dnnn]  [-n  string]  [-snnn]  [-lnnn]  [-ennn]  file 

DESCRIPTION 

lifinit  writes  a  LI  F  volume  header  on  a  volume  or  file. 

Options 

lifinit  recognizes  the  following  options  and  command-linearguments  which  can  appear  in  any  order: 

-vnnn  Sets  volume  size  to  nnn  bytes.  If  nnn  is  not  a  multiple  of  256,  it  is  rounded  down  to  the 
next  such  multiple. 

-dnnn  Sets  directory  size  to  nnn  file  entries.  If  nnn  is  not  an  integer  multiple  of  8,  it  is  rounded 
up  to  next  such  multiple. 

-n  string  Sets  the  volume  name  to  be  string.  Ifthe  -n  option  is  not  specified,  the  volume  name  is 
set  to  the  last  component  of  the  path  name  specified  by  file.  A  legal  LI  F  volume  name  is  6 
characters  long  and  is  limited  to  uppercase  letters  (A-Z),  digits  (0-9)  and  the  underscore 
character  (_).  The  first  character  (if  any)  must  be  a  letter.  The  utility  automatically  per- 
forms translation  to  create  legal  LIF  volume  names.  Therefore,  all  lowercase  letters  are 
converted  to  uppercase,  and  all  other  characters  except  numeric  and  underscore  are 
replaced  with  a  capital  letter  X.  If  the  volume  name  does  not  start  with  a  letter,  the 
volume  name  is  preceded  by  a  capital  letter  X.  The  volume  name  is  also  right-padded  with 
spaces  or  truncated  as  needed  to  be  six  characters  long.  If  -n  is  used  with  no  string,  the 
default  volume  name  is  set  to  6  spaces. 

set  the  initial  system  load  (ISL)  start  address  to  nnn  in  the  volume  label.  This  is  useful 
when  building  boot  media  for  Series  700/800  systems. 

specifies  the  length  in  bytes  of  the  ISL  code  in  the  LIF  volume. 

set  the  ISL  entry  point  to  nnn  bytes  from  the  beginning  of  the  ISL.  For  example,  specify- 
ing -e3272  means  that  the  ISL  entry  point  is  3272  (decimal)  bytes  from  the  beginning  of 
the  ISL  object  module. 

forces  the  directory  start  location  to  be  the  nearest  multiple  of  nnn  x  1024  bytes  from  the 
beginning  of  the  volume.  This  is  necessary  for  booting  Series  700/800  systems  from  LIF 
media. 

If  filedoes  not  exist,  a  regular  HP-UX  disk  file  is  created  and  initialized. 

The  default  values  for  volume  size  are  256  kilobytes  for  regular  files,  and  the  actual  capacity  of  the  device 
for  device  files. 

The  default  directory  size  is  a  function  of  the  volume  size.  A  percentage  of  the  volume  size  is  allocated  to 
the  volume  directory  as  follows: 


Volume  Size 

Directory  Size 

<2MB 

-1.3% 

>2MB 

-0.5% 

Each  directory  entry  occupies  32  bytes  of  storage.  The  actual  directory  space  is  subject  to  the  rounding 
rules  stated  above. 

Do  not  mount  the  special  file  while  using  lifinit . 
RETURN  VALUE 

lifinit  returns  exit  code  0  if  the  volume  is  initialized  successfully.  Otherwise  it  prints  a  diagnostic  mes- 
sage and  returns  nonzero. 

EXAMPLES 

I  nitializefile  x  to  be  a  LI  F  volume  containing  500000  bytes  with  10  directory  file  entries: 

lifinit  -v500000  -dlO  x 

I nitialize  device  /dev/rdsk/c0t6d0  as  a  LIF  volume  using  default  initialization  conditions  (device 
must  not  be  a  mounted  file  system  device): 


-snnn 

-lnnn 
-ennn 

-Knnn 
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lifinit  /dev/rdsk/c0t6d0 
WARNINGS 

To  prevent  media  corruption,  do  not  terminate  lifinit  once  it  has  started  executing. 

AUTHOR 

lifinit  was  developed  by  HP. 

SEE  ALSO 

lifcp(l),  lifted),  lifrename(l),  lifrm(l),  lif(4). 
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NAME 

lifls  -  list  contents  of  a  LI  F  directory 

SYNOPSIS 

lifls  [option]  name 

DESCRIPTION 

lifls  lists  the  contents  of  a  LI  F  directory  on  standard  output.  The  default  output  format  lists  file  names 
in  multiplecolumns  (similar  to  ls(l),  except  unsorted)  if  standard  output  is  a  character  special  file.  If  stan- 
dard output  is  not  a  tty  device,  the  output  format  is  one  file  name  per  line,  name  is  a  path  name  to  an  HP- 
UX  file  containing  a  LI  F  volume  and  optional  file  name.  If  name  is  a  volume  name,  the  entire  volume  is 
listed.  If  name  is  of  the  form  volume:file,  only  the  file  is  listed.  The  following  options  are  available,  and 
only  one  option  should  be  specified  with  a  given  command: 

-1  List  in  long  format,  giving  volume  name,  volume  size,  directory  start,  directory  size,  file  type, 
file  size,  file  start,  "implementation"  field  (in  hex),  date  created,  last  volume,  and  volume 
number. 

-C       Force  multiplecolumn  output  format  regardless  of  standard  output  type. 
-L       Return  the  content  of  the  "last  volume  flag"  in  decimal, 
-i       Return  the  content  of  the  "implementation"  field  in  hex. 
-v       Return  the  content  of  the  "volume  number"  in  decimal, 
-b  blist 

Report  only  on  files  using  block  numbers  specified  on  the  command  line  in  blist,  a  comma 
separated  list  of  block  numbers  in  DEV  BSIZE  units. 

Do  not  mount  the  special  file  while  using  lifls. 
DIAGNOSTICS 

lifls  returns  zero  if  the  directory  was  listed  successfully.  Otherwise  it  prints  a  diagnostic  and  returns 
nonzero. 

EXAMPLES 

lifls  -C  /dev/rdsk/c0t6d0 

AUTHOR 

lifls  was  developed  by  HP. 

SEE  ALSO 

lifcp(l),  lifinit(l),  lifrename(l),  lifrm(l),  lif(4). 
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NAME 

lifrename-  rename  LI  F  files 

SYNOPSIS 

lifrename  oldfile  newfile 

DESCRIPTION 

oldfile  is  a  full  LIF  file  specifier  (see  lif(4)  for  details)  for  the  file  to  be  renamed  (e.g.  lif  f  ile :  A_FILE). 
newfileisnew  name  to  be  given  to  the  file  (only  the  file  name  portion).  This  operation  does  not  includecopy 
or  delete.  Old  file  names  must  match  the  name  of  the  file  to  be  renamed,  even  if  that  file  name  is  not  a 
legal  LIF  name. 

Do  not  mount  the  special  file  while  using  lifrename . 
DIAGNOSTICS 

lifrename  returns  zero  if  the  file  name  is  changed  successfully.  Otherwise  it  prints  a  diagnostic  and 
returns  nonzero. 

EXAMPLES 

lifrename  lif file : A_FILE  B_FILE 
lifrename  /dev/dsk/c0t6d0 : ABC  CDE 

AUTHOR 

lifrename  was  developed  by  HP. 

SEE  ALSO 

lifcp(l),  lifinit(l),  lifls(l),  lifrm(l),  I  if  (4). 
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NAME 

lifrm  -  remove  a  LI  F  file 

SYNOPSIS 

lifrm  filel  ...  filen 

DESCRIPTION 

lifrm  removes  one  or  more  entries  from  a  LI  F  volume.  File  name  specifiers  are  as  described  in  I  if  (4). 
Do  not  mount  the  special  file  while  using  lifrm. 

DIAGNOSTICS 

lifrm  returns  zero  if  the  file  is  removed  successfully.  Otherwise  it  prints  a  diagnostic  and  returns 
nonzero. 

EXAMPLES 

lifrm  liffile:MAN 

lifrm  /dev/rdsk/c0t6d0 :F 

AUTHOR 

lifrm  was  developed  by  HP. 

SEE  ALSO 

lifcp(l),  lifinit(l),  lifls(l),  lifrename(l),  lif(4). 
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NAME 

line-  read  one  line  from  user  input 

SYNOPSIS 

line  [-t  timeout] 

DESCRIPTION 

line  copies  one  line  (up  to  a  new-line)  from  the  standard  input  and  writes  it  on  the  standard  output.  It 
returns  an  exit  code  of  1  on  EOF  and  always  prints  at  least  a  new-line.  It  is  often  used  within  shell  files  to 
read  from  the  user's  terminal. 

Options 

line  recognizes  the  following  command-line  option: 

-t  timeout  Timeout  after  timeout  seconds  where  timeout  is  an  integer  value  (if  a  non-integer  value  is 
specified,  it  is  converted  to  an  integer;  i.e.,  rounded  down).  A  blank  is  required  between 
-t  and  the  timeout  argument.  This  option  is  not  documented  in  posix  and  other  indus- 
try standards,  and  should  not  be  used  in  portable  applications. 

EXTERNAL  INFLUENCES 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

The  foil  owing  lines  in  a  shell  script  prompt  for  a  file  name  and  display  information  about  the  file: 

echo  'Enter  file  name:  \c' 
reply= 'line  * 
Is  -1  $reply 

To  limit  the  response  time  to  10  seconds,  use  the  form: 

reply=,line  -t  10' 

then  test  for  no  response.  If  no  response  occurs  before  timeout  expires,  a  default  behavior  should  be  pro- 
vided. 

WARNINGS 

This  command  is  likely  to  be  withdrawn  from  X/Open  standards.  Applications  using  this  command  might 
not  be  portableto  other  vendors'  systems.  As  an  alternative  read  is  recommended. 

SEE  ALSO 

sh(l),  read(2). 

STANDARDS  CONFORMANCE 

line:  SVI D2,  SVI D3,  XPG2,  XPG3 
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NAME 

listusers-  display  user  login  data 

SYNOPSIS 

listusers  [-g  groups]  [-1  logins] 

DESCRIPTION 

The  listusers  command  displays  data  concerning  user  logins.  The  output  shows  the  user  login  and  the 
/etc/passwd  comment  field  value  (e.g.,  user  name,  etc.).  The  default  displays  data  about  all  user 
logins. 

Options 

The  listusers  command  supports  the  foil  owing  options: 

-g  groups       Display  all  users  belonging  to  groups,  sorted  by  login.  A  comma  separated  list 
specifies  multiplegroups. 

-1  logins        Display  the  requested  logins.  A  comma  separated  list  specifies  multiplelogins. 

A  user  I  ogi  n  has  a  u  I D  of  100  or  greater. 

When  the  -1  and  -g  options  are  combined,  a  user  login  is  only  displayed  once,  even  though  the  login  may 
belong  to  multiplespecified  groups. 

EXAMPLES 

List  all  user  logins. 

listusers 

List  all  user  logins  in  the  group  cmds  and  the  users  bob,  john  and  otto,  removing  all  duplicates, 
listusers  -g  cmds  -1  bob, john, otto 

FILES 

/etc/passwd 
/etc /group 

SEE  ALSO 

passwd(l),  logi ns(lM ),  group(4),  passwd(4). 

STANDARDS  COMPLIANCE 

listusers: SVID3 
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NAME 

In  -  link  files  and  directories 

SYNOPSIS 

In  [-f]  [-i]  [-s]  filel  new_file 

In  [-f]  [-i]  [-s]  filel  [file2  ...]    dest_di rectory 

In  [-f]  [-i]  [-s]  directoryl  [directory2  ...]    dest  di  rectory 

DESCRIPTION 

The  In  command  links: 

•  filel  to  a  new  or  existing  new  file, 

•  filel  to  a  new  or  existing  file  named  filel  in  existing  destdi  rectory, 

•  filel,  file2,  ...  to  new  or  existing  files  of  the  same  name  in  existing  destdi  rectory, 

•  directoryl,  directory2,  ...  to  new  directories  of  the  same  name  in  existing  destdi  rectory, 

•  or  it  creates  symbolic  links  between  files  or  between  directories. 

If  links  are  to  destdi  rectory,  corresponding  file  or  directory  names  in  that  directory  are  linked  to  filel, 

file2        or  directoryl,  directory2        etc.,  as  appropriate.  If  two  or  more  existing  files  or  directories 

(excluding  destination  file  name  new  file)  are  specified,  the  destination  must  be  a  directory.  If  new  file 
already  exists  as  a  regular  file  (or  link  to  another  file),  its  contents  (or  the  existing  link)  and  its  ACL  are 
destroyed  only  if  the  -f  option  is  specified.  TheACL  on  the  newfile  after  the  link  is  the  same  as  that  of 
the  sourcefilefile. 

If  the  -f  and  -i  options  are  specified  and  the  link  being  created  is  the  name  of  an  existing  link  or  ordinary 
file  and  the  access  permissions  of  the  file  forbid  writing,  In  asks  permission  to  overwrite  the  file.  If  the 
access  permissions  of  the  directory  forbid  writing,  In  aborts  and  returns  with  the  error  message: 

cannot  unlink  new  file 

(even  if  the  file  is  an  ordinary  file  and  not  a  link  to  another  file).  When  asking  for  permission  to  overwrite 
an  existing  file  or  link,  In  prints  the  mode  (see  chmod(2)  and  Access  Control  Lists  below),  followed  by  the 
first  letters  of  the  words  yes  and  no  in  the  current  native  language,  prompting  for  a  response,  and  reading 
one  line  from  the  standard  input.  If  the  response  is  affirmative  and  is  permissible,  the  operation  occurs;  if 
not,  the  command  proceeds  to  the  next  source  file,  if  any. 

Hard  links  are  created  with  the  same  ownerships  and  permissions  as  the  file  or  directory  to  which  they  are 
linked.  If  ownership  or  permissions  are  changed  on  a  link  or  file,  the  same  changes  appear  on  correspond- 
ing hard  links.  The  In  command  does  not  permit  hard  links  toa  directory. 

Symbolic  links  are  created  with  the  ownership  of  the  creator  and  the  permissions  are  of  the  creator's 
current  umask.  Once  created,  the  symbolic  link  ownership  and  permissions  will  not  change,  si  nee  the  mode 
and  ownership  of  the  symbolic  link  is  ignored  by  the  system. 

If  filel  is  a  file  and  new  file  is  a  link  to  an  existing  file  or  an  existing  file  with  other  links,  new  file  is  disas- 
sociated from  the  existing  file  and  links  and  linked  to  filel.  When  In  creates  a  link  to  a  new  or  existing  file 
name,  ownerships  and  permissions  are  always  identical  to  those  for  the  file  to  which  it  is  linked.  If  chown, 
chgrp,  or  chmod  is  used  to  change  ownership  or  permissions  of  a  file  or  link,  the  change  applies  to  the 
file  and  all  associated  links.  The  last  modification  time  and  last  access  time  of  the  file  and  all  associated 
links  are  identical  (see  chown(l)  and  chmod(l)). 

For  a  discussion  of  symbolic  links,  see  symlink(4). 
Options 

The  In  command  recognizes  the  following  options: 

-f       Force  existing  destination  path  names  to  be  removed  to  allow  the  link. 

-i  Writea  prompt  to  the  standard  error  output  requesting  confirmation  for  each  link  that  would 
overwrite  an  existing  file.  This  option  takes  effect  only  if  used  in  conjunction  with  the  -f 
option. 

-s  Cause  In  to  create  symbolic  links  instead  of  the  usual  hard  links.  A  symbolic  link  contains 
the  name  of  the  file  to  which  it  is  linked.  The  referenced  file  is  used  when  an  open  ()  opera- 
tion is  performed  on  the  link  (see  open(2)).  A  stat  ()  on  a  symbolic  link  returns  the  linked- 
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to  file;  an  lstat  ()  must  be  performed  to  obtain  information  about  the  link  (see  stat(2)).  A 
readlink()  call  can  be  used  to  read  the  contents  of  the  symbolic  link  (see  readlink(2)). 
Symbolic  links  may  span  file  systems  and  refer  to  directories. 

Access  Control  Lists  (ACLs) 

If  optional  ACL  entries  are  associated  with  new  file,  In  displays  a  plus  sign  (+)  after  the  access  mode  when 
asking  permission  to  overwrite  the  file. 

If  new  file  is  a  new  file,  it  inherits  the  access  control  list  of  fil el,  altered  to  reflect  any  difference  in  owner- 
ship between  the  two  files  (see  acl(5)  and  aclv(5)).  In  J  FS  file  systems,  new  files  created  by  In  do  not 
inherit  their  parent  directory's  default  ACL  entries  (if  any),  but  instead  retain  their  original  ACLs. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single  byte  and/or  multi byte  characters. 

LANG  and  LC_CTYPE  determine  the  local  language  equivalent  of  y  (for  yes/no  queries). 
LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used  as 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  C  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  In  behaves  as  if  all  internationalization  variables  are  set  to  C.  See  envi  ron (5). 

I  nternational  Code  Set  Support 

Single  byte  and  multi  byte  character  code  sets  are  supported. 

EXAMPLES 

The  following  command  creates  filel  and  file2  in  dest_dir,  which  are  linked  back  to  the  original 
files  filel  and  file2: 

In  -f  filel  file2  dest_dir 

If  filel  and/or  f ile2  exists  in  the  destination  directory,  it  is  removed  and  replaced  by  a  link  to  filel 
or  file2,  respectively.  If  existing  file  filel  or  file2  is  a  link  to  another  file  or  a  file  with  links,  the 
existing  file  remains.  Only  the  link  is  broken  and  replaced  by  a  new  link  to  filel  or  f  ile2 . 

WARNINGS 

In  does  not  create  hard  I  inks  across  file  systems. 

DEPENDENCIES 
NFS 

Access  control  lists  of  networked  files  are  summarized  (as  returned  in  st_mode  by  stat() ),  but  not 
copied  to  the  new  file.  When  using  In  on  such  files,  a  +  is  not  printed  after  the  mode  value  when  asking 
for  permission  to  overwrite  a  file. 

AUTHOR 

In  was  developed  by  AT&T,  the  University  of  California,  Berkeley  and  HP. 
SEE  ALSO 

cp(l),  cpio(l),  mv(l),  rm(l),  link(lM),  readlink(2),  stat(2),  symlink(2),  symlink(4),  acl(5),  aclv(5). 

STANDARDS  CONFORMANCE 

In:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

locale-  get  locale-specific  (NLS)  information 

SYNOPSIS 

locale  [  -a  [  32  |   64  ]  |  —A  |  — m  ] 

locale  [  -ck  ]  name  ... 
DESCRIPTION 

The  locale  command  displays  information  about  the  current  locale  or  about  avail  able  locales. 

When  invoked  without  arguments,  locale  displays  the  name  and  actual  or  implied  value  of  each  of  the 
locale-related  environment  variables  in  the  order  shown  below,  one  per  line: 

LANG 
LC_CTYPE 
LC_COLLATE 
LC_MONE  TARY 
LC_NUMERIC 
LC_TIME 
LC_ME  S  SAGE  S 
LC_ALL 

An  actual  value  is  the  value  the  variable  actually  has  in  the  user's  environment.  An  implied  value  is 
derived  from  the  value  of  another  variable.  I  mplied  values  are  displayed  enclosed  in  double  quotes,  while 
actual  val  ues  are  unquoted. 

The  determination  of  implied  values  is  that  if  the  variable  LC_ALL  is  present  and  has  a  non-null  value, 
that  is  the  actual  value  for  LC_ALL,  and  all  of  the  other  variables  take  its  value  as  an  implied  value.  If 
LC_ALL  is  not  set,  all  of  the  LC_*  variables  that  are  set  are  shown  with  their  value  as  an  actual  value. 
Any  that  have  no  value  are  shown  with  the  value  of  the  LANG  environment  variable  as  their  implied  value. 
LC_ALL  is  displayed  as  LC_ALL=\n  if  it  has  no  value. 

The  locale  command  can  take  multiple  arguments,  which  may  be  locale  category  names,  locale  key- 
words, or  the  special  word  charmap  (see  localedef(llM)  for  a  description  of  locale  keywords  and  charmaps). 
If  an  argument  is  a  keyword,  the  value  associated  with  that  keyword  in  the  current  environment  is 
displayed  and  possibly  other  information,  depending  on  selected  options.  If  an  argument  is  a  category 
name  (i.e.,  LC_*),  the  values  of  all  keywords  defined  in  that  category  are  displayed.  If  an  argument  is  the 
special  word  charmap,  the  charmap  file  (if  any)  that  was  used  in  the  definition  of  the  current  locale  is 
displayed. 

Non-printable  characters  are  printed  as  hexadecimal  values  in  theform, 
\xhh 

except  that  if  a  different  escape  character  has  been  defined  for  the  locale,  it  is  displayed  instead  of  the  "\ ". 

Options 

Thefollowing  options  are  available: 

-a  List  all  availablelocales.  These  are  the  possible  meaningful  values  that  can  be  assigned  to 

LANG  or  any  of  the  LC_*  variables  on  the  system.  They  are  dependent  upon  which  locales 
have  been  installed  on  the  system.  By  default  on  a  32-bit  system,  the  locales  in 
/usr/lib/nls/loc/locales  are  listed.  By  default  on  a  64-bit  system,  the  locales  in 
/usr/lib/nls/loc/pa20_64/locales  are  listed.  This  option  takes  32  (for  ILP32, 
32-bit  int,  long,  pointer,  32-bit  offset)  or  64  (for  LP64,  64-bit  long,  pointer,  64-bit  offset)  as 
its  argument. 

-a  Display  32-bit  locales  for  32-bit  and  64-bit  systems, 

-a  32     Display  32-bit  locales  for  32-bit  and  64-bit  systems. 

-a  64     Display  only  64-bit  locales  on  a  64-bit  system.  If  executed  on  a  32-bit  system,  an 
error  message  is  returned. 

-A  List  32-bit  locales  on  a  32-bit  system.  List  both  32-bit  and  64-bit  bit  locales  on  a  64-bit  sys- 

tem. 

-m  Display  a  list  of  avail  able  charmap  files  on  the  system.  See  localedef(lM)  for  a  definition  of 

charmap  files  and  their  usage. 
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-c  Display  names  of  locale  categories  that  have  been  selected  either  explicitly  or  by  giving  a 

keyword  contained  therein.  This  option  may  be  used  with  the-k  option. 

-k  Display  names  of  keywords  that  have  been  selected  either  explicitly  or  by  providing  their 

containing  category  as  an  argument.  Keyword  names  and  values  are  displayed  as: 

<keyword  >=  <va  I  u  e> 

Without  the  -k  option,  only  the  values  are  displayed.  This  option  can  be  used  with  the  -c 
option. 

name      Specify  the  locale  category  name,  locale  keyword,  or  the  special  word  charmap. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is  unset 
or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  contains  an 
invalid  setting,  locale  will  behave  asif  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

LC_ALL,  when  set  to  a  non-empty  string  value,  overrides  the  values  of  all  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  content  of  diagnostic 
messages  written  to  standard  error,  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalog  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

RETURN  VALUE 

The  locale  command  exits  with  one  of  the  foil  owing  values: 

0   All  requested  information  was  found  and  displayed  successfully. 
>0    An  error  occurred  in  either  finding  or  displaying  the  information. 

EXAMPLES 

If  the  locale  environment  variables  are  set  as: 

LANG=fr_FR. iso88591 
LC_COLLATE=C 

the  command: 

locale 

gives  the  foil  owing  output: 

LANG=fr_FR. iso88591 
LC_CTYPE=" fr_FR. iso88591" 
LC_COLLATE=C 

LC_MONETARY="fr_FR. iso88591" 
LC_NUMERIC="fr_FR. iso88591" 
LC_TIME=" fr_FR. iso88591" 
LC_MESSAGES=" f r_FR . iso88591 " 
LC_ALL= 

The  command: 

LC_ALL=POSIX  locale  -ck  decimal_point 

produces: 

LC_NUMERIC  decimal_point=" . " 
If  LANG  is  set  toPOSlX  and  no  other  locale  variables  are  set,  the  command: 
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locale  LC_NUMERIC 

produces: 


ii  ii 
ii  ii 


which  correspond  to  the  keywords  decimal  point,  thousands  sep,  grouping,  and  alt  digit. 
SEE  ALSO 

localedef(lM),  localeconv(3C),  nl_langinfo(3C),  setlocale(3C),  charmap(4),  localedef(4),  environ(5),  lang(5). 

STANDARDS  CONFORMANCE 

locale:  XPG4,  POSIX.2 
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NAME 

lock  -  reserve  a  terminal 


SYNOPSIS 

lock 


DESCRIPTION 

lock  requests  a  password  from  the  user,  then  prints  LOCKED  on  the  terminal  and  refuses  to  relinquish 
the  terminal  until  the  password  is  repeated.  If  the  user  forgets  the  password,  the  only  recourse  is  to  log  in 
elsewhere  and  kill  the  lock  process. 
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NAME 

logger  -  make  entries  in  the  system  log 
SYNOPSIS 

logger  [-t  tag]  [-p  pri]  [-i]  [-f  file]  [message...] 
DESCRIPTION 

The  logger  command  provides  a  program  interface  to  the  syslogO  system  log  module  (see 
syslogOO). 

A  message  can  be  given  on  the  command  line,  which  is  logged  immediately,  or  a  file  is  read  and  each  line  is 
logged.  I  f  no  file  or  message  is  specified,  the  contents  of  the  standard  i  nput  are  logged. 

Options 

The  logger  command  recognizes  the  foil  owing  command-line  options  and  arguments: 

-t  tag  Mark  every  line  in  the  log  with  the  specified  tag.  The  default  is  the  value  returned  by 

getlogin()  (see  getlogin(3C)).  lfgetlogin()  returns  NULL,  syslog  is  the 
default. 

-p  pri  Enter  the  message  with  the  specified  priority.  The  priority  can  be  specified  numeri- 

cally or  as  a  facility .  level  pair.  For  example, -p  local3.info  logs  the  message 
or  messages  as  informational  level  in  the  local3  facility.  The  default  is 
user. notice. 

-i  Log  the  process  I D  of  the  logger  process  with  each  line, 

-f  file  Log  the  contents  of  the  specified  file. 

message         The  message  to  log;  if  not  specified,  the  file  specified  by  the  -f  option  or  standard 
input  is  logged. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  logger  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

Send  the  message  System  rebooted  to  the  syslogd  daemon: 

logger  System  rebooted 

Send  output  from  the  users  command  (see  users(l)  to  the  syslogd  daemon,  marked  as  level  info  and 
facility  localO .  The  message  is  tagged  with  the  string  USERS: 

users    |   logger  -p  localO . info  -t  USERS 

Send  the  message  System  going  down  immediately !  !  !  to  the  syslog  daemon,  at  the  emerg 
level  and  user  facility: 

logger  -p  user. emerg   "System  going  down  immediately!!!" 
WARNINGS 

The  logger  command  has  no  effect  if  the  syslogd  daemon  (see  syslogd (1M))  is  not  running  on  the  sys- 
tem. 

Messages  written  in  locales  other  than  thePOSix/C  locale  are  not  supported. 
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AUTHOR 

logger  was  developed  by  the  University  of  California,  Berkeley. 

SEE  ALSO 

syslogd(lM),  getlogin(3C),  syslog(3C). 

STANDARDS  CONFORMANCE 

logger:  XPG4,  POSIX.2 
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NAME 

login  -  sign  on;  start  terminal  session 

SYNOPSIS 

login  [name  [env-var]  ...] 

DESCRIPTION 

The  login  command  is  used  at  the  beginning  of  each  terminal  session  to  properly  identify  a  prospective 
user,  login  can  be  invoked  as  a  user  command  or  by  the  system  as  an  incoming  connection  is  established, 
login  can  also  be  invoked  by  the  system  when  a  previous  user  shell  terminates  but  the  terminal  does  not 
disconnect. 

If  login  is  invoked  as  a  command,  it  must  replace  the  initial  command  interpreter  (the  user's  login  shell). 
This  is  accomplished  with  the  shell  command 

exec  login 

The  user's  login  name  is  requested,  if  it  is  not  specified  on  the  command  line,  and  the  corresponding  pass- 
word isobtained,  if  required,  with  the  following  prompts: 

login : 
Password : 

Terminal  echo  is  turned  off  (where  possible)  during  password  entry  to  prevent  written  records  of  the  pass- 
word. If  the  account  does  not  have  a  password,  and  the  authentication  profile  for  the  account  requires  one, 
login  invokes  pam_chauthtok ( )  to  establish  one  for  the  account.  On  a  trusted  system,  login 
displays  the  last  successful  and  unsuccessful  login  times  and  terminal  devices. 

As  a  security  precaution,  some  installations  use  an  option  that  requires  a  second  "dialup"  password.  This 
occurs  only  for  dialup  connections,  and  is  requested  with  the  prompt: 

dialup  password: 

Both  passwords  must  be  correct  for  a  successful  login  (see  dial  ups(4)  for  detailson  dialup  security). 

If  password  aging  is  activated,  the  user's  password  may  have  expired.  pam_chauthtok  ( )  is  invoked  to 
change  the  password.  I  n  an  untrusted  environment,  the  user  is  required  to  re-login  after  a  successful  pass- 
word change  (see  passwd(l)). 

After  three  unsuccessful  login  attempts,  a  HANGUP  signal  is  issued.  If  a  login  is  not  successfully  completed 
within  a  certain  period  of  time  (for  example,  one  minute),  the  terminal  is  silently  disconnected. 

After  a  successful  login,  the  accounting  files  are  updated,  user  and  group  IDs,  group  access  list,  and  work- 
ing directory  are  initialized,  and  the  user's  command  interpreter  (shell)  is  determined  from  corresponding 
user  entries  in  the  files  /etc/passwd  and  /etc/logingroup  (see  passwd(4)  and  group(4)).  If 
/etc/passwd  does  not  specify  a  shell  for  the  user  name,  /usr/bin/sh  is  used  by  default,  login 
then  forks  the  appropriate  shell  by  using  the  last  component  of  the  shell  path  name  preceded  by  a  -  (for 
example,  -sh  or  -ksh).  When  the  command  interpreter  is  invoked  with  its  name  preceded  by  a  minus  in 
this  manner,  the  shell  performs  its  own  initialization,  including  execution  of  profile,  login,  or  other  initiali- 
zation scripts. 

For  example,  if  the  user  login  shell  is  the  Bourne,  Korn,  or  POSIX  shell  (see  sh-bourne(l),  ksh(l),  or  sh- 
posix(l),  respectively),  the  shell  executes  the  profile  files  /etc/profile  and  $HOME/  .profile  if  they 
exist  (and  possibly  others  as  well).  Depending  on  what  these  profile  files  contain,  messages  regarding  mail 
in  the  user's  mail  file  or  any  messages  the  user  may  have  received  since  the  user's  last  login  may  be 
displayed. 

If  the  command  name  field  is  *,  a  chroot  ()  to  the  directory  named  in  the  directory  field  of  the  entry  is 
performed.  At  that  point,  login  is  re-executed  at  the  new  level,  which  must  have  its  own  root  structure, 
includinga  /usr/bin/login  command  and  an  /etc/passwd  file. 

For  the  normal  user,  the  basic  environment  variables  (see  environ  (5))  are  initialized  to: 

HOME=  I  ogi  ndi  rectory 
LOGNAME=  I  ogi  nname 
MAIL=/var /mail/1  ogi  n  name 
PATH= : /usr/bin 
SHELL=login_shell 
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I  ogindi  rectory,  login  name,  and  login  shell  are  taken  from  the  corresponding  fields  of  the  passwd  file 
entry  (see  passwd (4)). 

For  superuser,  PATH  is  set  to: 

PATH= : /usr/ sbin : /usr/bin : /sbin 

I  n  the  case  of  a  remote  login,  the  environment  variable  TERM  is  also  set  to  the  remote  user's  terminal  type. 

The  environment  can  be  expanded  or  modified  by  supplying  additional  arguments  to  login,  either  at  exe- 
cution time  or  when  login  requests  the  user's  login  name.  The  arguments  can  take  either  the  form  value 
or  varname=value,  where  varname  is  a  new  or  existing  environment  variable  name  and  value  is  a  value  to 
be  assigned  to  the  variable. 

An  argument  in  the  first  form  (without  an  equals  sign)  is  placed  in  the  environment  as  if  it  were  entered  in 
the  form 

Ln=value 

where  n  is  a  number  starting  at  0  that  is  incremented  each  time  a  new  variable  name  is  required. 

An  argument  in  the  second  form  (with  an  equalssign)  is  placed  into  the  environment  without  modification. 

If  the  variable  name  (Ln  or  varname)  already  appears  in  the  environment,  the  new  value  replaces  the  older 
one. 

There  are  two  exceptions.  ThevariablesPATH  and  SHELL  cannot  be  changed.  This  prevents  users  logged 
in  with  restricted  shell  environments  from  spawning  secondary  shells  that  are  not  restricted. 

Both  login  and  getty  understand  simple  single-character  quoting  conventions.  Typing  a  backslash  in 
front  of  a  character  quotes  it  and  allows  the  inclusion  of  such  things  as  spaces  and  tabs. 

If  /var/adm/btmp  is  present,  all  unsuccessful  login  attempts  are  logged  to  that  file.  This  feature  is  dis- 
abled if  the  file  is  not  present.  The  lastb  command,  (see  last(l)),  displays  a  summary  of  bad  login 
attempts  for  users  with  read  access  tobtmp. 

If  the  /etc/securetty  file  is  present,  login  security  is  in  effect,  i.e.,  root  is  allowed  to  log  in  success- 
fully only  on  the  ttys  listed  in  this  file.  Restricted  ttys  are  listed  by  device  name,  one  per  line.  Valid  tty 
names  are  dependent  on  the  installation.  An  example  is 

console 

ttyOl 

ttyal 

etc. 

Note  that  this  feature  does  not  inhibit  a  normal  user  from  using  the  su  command  (see  su(l)). 

HP-UX  Smart  Card  Login 

If  the  user  account  is  configured  to  use  a  Smart  Card,  the  user  password  is  stored  in  the  card.  This  pass- 
word has  characteristics  identical  to  a  normal  password  stored  on  the  system. 

In  order  to  login  using  a  Smart  Card  account,  the  card  must  be  inserted  into  the  Smart  Card  reader.  The 
user  is  prompted  for  a  PIN  (personal  identification  number)  instead  of  a  password  during  authentication. 
The  prompts  are: 

login : 
Enter  PIN: 

The  password  is  retrieved  automatically  from  the  Smart  Card  when  a  valid  PI  N  is  entered.  Therefore,  it  is 
not  necessary  to  know  the  password,  only  the  PIN. 

The  card  is  locked  if  an  incorrect  PIN  is  entered  three  consecutive  times.  It  may  be  unlocked  only  by  the 
card  issuer. 

SECURITY  FEATURES 

On  a  trusted  system,  login  prohibits  a  user  from  logging  in  if  any  of  the  foil  owing  is  true: 

•  The  password  for  the  account  has  expired  and  the  user  cannot  successfully  change  the  password. 

•  The  password  lifetime  for  the  account  has  passed. 

•  The  time  between  the  last  login  and  the  current  time  exceeds  the  time  allowed  for  login  intervals. 
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•  The  administrative  lock  on  the  account  has  been  set. 

•  The  maximum  number  of  unsuccessful  login  attempts  for  the  account  has  been  exceeded. 

•  The  maximum  number  of  unsuccessful  login  attempts  for  the  terminal  has  been  exceeded. 

•  The  administrative  lock  on  the  terminal  has  been  set. 

•  Theterminal  has  an  authorized  user  list  and  the  user  is  not  on  it. 

•  Theterminal  has  time  of  day  restrictions  and  the  current  time  is  not  within  the  allowable  period. 

On  a  trusted  system,  login  allows  superuser  to  log  in  on  the  console  unless  /etc/securetty  exists 
and  does  not  contain  console. 

Refer  to  the  /etc/def ault/security  file  in  the  security(4)  man  page  for  detailed  information  on 
configurable  parameters  that  affect  the  behavior  of  this  command.  Currently  supported  parameters  are: 

ABORT_LOGIN_ON_MI S  S ING_HOMED I R 
NOLOGIN 

NUMBER_OF_LOGINS_ALLOWED 

EXTERNAL  INFLUENCES 
Environment  Variables 

HOME      U  ser's  home  di  rectory. 

MAIL      Where  to  I  ook  for  mai  I . 

PATH      Path  to  be  searched  for  commands. 

SHELL     Which  command  interpreter  is  being  used. 

TERM      U  ser's  termi  nal  type. 

varname  User-specified  named  variables. 

Ln  User-specified  unnamed  variables. 

DIAGNOSTICS 

The  following  diagnostics  appear  if  the  associated  condition  occurs: 

. rhosts  is  a  soft  link 

The  personal  equivalence  file  is  a  symbolic  link. 
Bad   . rhosts  ownership 

The  personal  equivalence  file  is  not  owned  by  the  local  user  or  by  a  user  with  appropriate  privileges. 
Bad  group  id 

setgid()  failed  (see setuid(2)). 
Bad  user  id 

setuid()  failed  (see setuid(2)). 
Cannot  open  password  file 

Consult  system  administrator. 
Locuser  too  long 

The  indicated  string  was  too  long  for  login's  internal  buffer. 
Login  incorrect 

User  name  and  password  cannot  be  matched. 

No  /usr/bin/login  or  /etc/login  on  root 

Attempted  to  log  in  to  a  subdirectory  root  that  does  not  have  a  subroot  login  command.  That  is,  the 
passwd  file  entry  had  shell  path  *,  but  the  system  cannot  find  a  login  command  under  the  given 
home  directory. 

No  directory 

Consult  system  administrator. 
No  Root  Directory 
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Attempted  to  log  in  to  a  subdirectory  root  that  does  not  exist.  That  is,  the  passwd  file  entry  had 
shell  path  *,  but  the  system  cannot  chroot  ()  to  the  given  home  directory. 


The  user  shell  (/usr/bin/sh  if  shell  name  is  null  in  /etc/passwd)  could  not  be  started  with  the 
exec  command.  Consult  system  administrator. 

No  utmp  entry.   You  must  exec  "login"   from  the  lowest  level  "sh" 

Attempted  to  execute  login  as  a  command  without  using  the  shell's  exec  internal  command  or 
from  other  than  the  initial  shell.  The  current  shell  is  terminated. 

Remuser  too  long 

The  indicated  string  was  too  long  for  login's  internal  buffer. 
Terminal  type  too  long 

The  indicated  string  was  too  long  for  login's  internal  buffer. 
Unable  to  change  to  directory  name 

Cannot  chdir  to  the  user's  home  directory. 
Your  password  has  expired.     Choose  a  new  one 

Password  aging  is  enabled  and  the  user's  password  has  expired. 

WARNINGS 

If  /etc/group  is  linked  to  /etc/logingroup,  and  group  membership  for  the  user  trying  to  log  in  is 
managed  by  the  Network  Information  Service  (NIS),  and  no  NIS  server  is  ableto  respond,  login  waits 
until  a  server  does  respond. 

DEPENDENCIES 

Pluggable  Authentication  Modules  (PAM) 

PAM  is  an  Open  Group  standard  for  user  authentication,  password  modification,  and  validation  of  accounts. 
In  particular,  pam_authenticate  ( )  is  invoked  to  perform  all  functions  related  to  login.  This 
includes  retrieving  the  password,  validating  the  account,  and  displaying  error  messages. 
pam_chauthtok  ( )  is  invoked  during  password  expiration  or  establishment. 

HP  Process  Resource  Manager 

If  the  optional  HP  Process  Resource  Manager  (PRM)  software  is  installed  and  configured,  the  login  shell  is 
launched  in  the  user's  initial  process  resource  group.  If  the  user's  initial  group  is  not  defined,  the  shell  runs 
in  the  user  default  group  (PRMID=1).  See  prmconfig(l)  for  a  description  of  how  to  configure  HP  PRM,  and 
prmconf  (4)  for  a  description  of  how  the  user's  initial  process  resource  group  is  determined. 


No  shell 


AUTHOR 


login  was  developed  by  AT&T  and  HP. 


FILES 


$HOME/ .profile 

$HOME/.rhosts 

/  etc/ d__passwd 

/etc/dialups 

/ etc/hosts . equiv 

/etc/ logingroup 

/etc/motd 

/etc/passwd 

/etc/profile 

/ etc/ securetty 

/etc /utmp 

/tcb/files/auth/*/* 
/ var / adm/btmp 
/ var/ adm/ wtmp 
/var /mail/  loginname 
/ etc/ default/ security 


Personal  profile  (individual  user  initialization) 
Personal  equivalence  file  for  the  remote  login  server 
Dialup  security  encrypted  passwords 
Lines  which  require  dial  up  security 

System  list  of  equivalent  hosts  allowing  logins  without  passwords 
Group  file  —  defines  group  access  lists 
M  essage-of-the-day 

Password  file  —  defines  users,  passwords,  and  primary  groups 
System  profile  (initialization  for  all  users) 
L  i  st  of  val  i  d  ttys  for  root  I  ogi  n 
Users  currently  logged  in 
The  trusted  system  password  database 
History  of  bad  login  attempts 
History  of  logins,  logouts,  and  datechanges 


Security  defaults  configuration  file 


Mai  I  box  for  user  loginname 
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SEE  ALSO 

csh(l),  groups(l),  ksh(l),  last(l),  mail(l),  newgrp(l),  passwd(l),  sh(l),  sh-bourne(l),  sh-posix(l),  su(l), 
getty(lM),  initgroups(3C),  dialups(4),  group(4),  passwd(4),  profile(4):  security(4),  utmp(4),  environ(5). 

HP  Process  Resource  Manager 

prmconfig(l),  prmconf(4)  in  HP  Process  Resource  Manager  Users  Guide. 

Pluggable  Authentication  Modules  (PAM) 

pam_acct_mgmt(3),  pam_authenticate(3),  pam_chauthtok(3). 

HP-UX  Smart  Card  Login 

scpin(l),  scsync(l). 
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NAME 

logname-  get  login  name 

SYNOPSIS 

logname 

DESCRIPTION 

logname  writes  the  user's  login  name  to  standard  output.  The  login  name  is  equivalent  to  that  returned 
by  getlogin()  (see  getlogin(3C)). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  diagnostic  messages  are  displayed. 

FILES 

/etc/profile 

SEE  ALSO 

env(l),  login(l),  getlogin(3C),  logname(3C):  environ(5). 

STANDARDS  CONFORMANCE 

logname:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

lorder  -  find  ordering  relation  for  an  object  library 

SYNOPSIS 

lorder  [files] 

DESCRIPTION 

The  input  consists  of  one  or  more  object  or  archive  library  files  (see  ar(l))  placed  on  the  command  line  or 
read  from  standard  input.  The  standard  output  is  a  list  of  pairs  of  object  file  names,  meaning  that  the  first 
file  of  the  pair  refers  to  external  identifiers  defined  in  the  second.  Output  can  be  processed  by  tsort  to 
find  an  ordering  of  a  library  suitablefor  one-pass  access  by  Id  (see  tsort(l)  and  I d (1)).  Note  that  the  link 
editor  Id  is  capable  of  multiple  passes  over  an  archive  in  the  archive  format  and  does  not  require  that 
lorder  be  used  when  building  an  archive.  Using  the  lorder  command  may,  however,  allow  for  a 
slightly  more  efficient  access  of  the  archive  during  the  link  edit  process. 

The  symbol  table  maintained  by  ar  allows  Id  to  randomly  access  symbols  and  files  in  the  archive,  making 
theuseof  lorder  unnecessary  when  buildingarchivelibraries(seear(l)). 

EXTERNAL  INFLUENCES 
Environment  Variables 

The  following  internationalization  variables  affect  the  execution  of  lorder: 

LANG 

Determines  the  locale  category  for  native  language,  local  customs  and  coded  character  set  in  the 
absenceof  LC_ALL  and  other  LC_*  environment  variables.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  C  (see  lang(5))  is  used  instead  of  LANG. 

LC_ALL 

Determines  the  values  for  all  locale  categories  and  has  precedence  over  LANG  and  other  LC_* 
environment  variables. 

LC_COLLATE 

Determines  the  locale  category  for  character  collation. 

LC_CTYPE 

Determines  the  locale  category  for  character  handlingfunctions. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic  messages 
written  to  standard  error. 

LC_NUMERIC 

Determines  the  locale  category  for  numeric  formatting. 

NLSPATH 

Determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

If  any  internationalization  variable  contains  an  invalid  setting,  lorder  behaves  as  if  all  internationaliza- 
tion variables  are  set  toe.  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

Build  a  new  library  from  existing  .  o  files: 

ar  cr  library    'lorder  *.o    |  tsort1 

When  creating  libraries  with  so  many  objects  that  the  shell  cannot  properly  handle  the  *  .  o  expansion,  the 
following  techniquemay  prove  useful: 

Is    |   grep  ' .0$'    I   lorder    |   tsort    |   xargs  ar  cq  library 
WARNINGS 

Object  files  whose  names  do  not  end  with  .0  are  overlooked,  even  when  contained  in  library  archives. 
Their  global  symbols  and  references  are  attributed  to  some  other  file. 
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FILES 

/var/tmp/*symref    temporary  files 
/var/tmp/*symdef 

SEE  ALSO 

System  Tools: 

ar(l)  create  archived  libraries 

I d (1)  invoke  the  link  editor 

Miscellaneous: 

tsort(l)  produce  an  ordered  list  of  items  (topological  sort) 

STANDARDS  CONFORMANCE 

lorder:  SVID2,  SVID3,  XPG2,  XPG4 
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NAME 

Ip,  Ipalt,  cancel  -  print/alter/cancel  requests  on  an  LP  printer  or  plotter 
SYNOPSIS 

lp  [-c]  [-ddest]  [-m]  [-nnumber]  [-ooption]  [-ppriority]  [-s]  [-ttitle]  [-w]  [file  ...] 
Ipalt  id  [-ddest]  [-i]  [-m]  [-nnumber]  [-ooption]  [-ppriority]  [-s]  [-ttitle]  [-w] 
cancel  [id  ...]  [printer  ...]  [-a]  [-e]  [-i]  [-uuser] 

DESCRIPTION 

The  lp  command  queues  files  for  printing.  The  Ipalt  command  changes  information  in  a  queued 
request.  The  cancel  command  deletes  a  queued  request. 

Ip  Command 

The  lp  command  arranges  for  the  named  files,  file  and  associated  information  (collectively  called  a 
request)  to  be  queued  for  output  to  a  printer  or  plotter  in  the  LP  (line  printer)  subsystem.  The  process  is 
called  printing,  regardless  of  the  actual  output  device. 

lp  associates  a  unique  identifier  with  each  request  and  writes  it  to  standard  output,  using  the  message: 

request  id  is  dest-sequence  (fileinfo) 

The  request  id  is  dest-sequence,  which  can  be  used  later  to  alter,  cancel,  or  find  the  status  of  the  request 
(see  Ipalt  and  cancel  below,  and  Ipstat(l)). 

For  example,  in  the  foil  owing  message, 

request  id  is  pr471f 8e-2410    (1  file) 

the  request  ID  ispr471f  8e-2410. 


Ip  Options  and  Arguments 

lp  recognizes  the  following  options  and  arguments.  The  keyletter  options  can  be  specified  in  any  order. 
Thefile  ...  names  must  be  last.  Blanks  are  not  permitted  between  a  keyletter  and  its  argument. 

file  ...  Print  each  named  file.  If  no  file  names  are  specified,  standard  input  is  assumed.  The 

hyphen  symbol  (-)  also  specifies  standard  input  and  can  be  intermixed  on  the  command 
line  with  file  names.  Files  are  printed  in  the  same  order  in  which  they  are  specified. 

-c  Copy  the  named  files  to  LP  subsystem  spooling  directories. 

Normally,  the  files  are  linked  into  a  spool  directory.  The  ownership  and  mode  of  the  linked 
files  remain  unchanged.  If  the  -c  option  is  given,  or  linking  is  not  possible  (perhaps 
because  the  printer  is  not  physically  attached  to  the  local  system  or  cluster),  the  files  are 
copied  into  the  spool  directories.  The  ownership  and  mode  of  the  copies  are  set  to  allow 
read  access  to  owner  lp  and  group  bin  only. 

If  the  files  are  linked  rather  than  copied,  any  changes  made  to  the  named  files  after  the 
request  is  made  but  before  it  is  printed  will  be  reflected  in  the  printed  output.  Standard 
input  is  always  copied  instead  of  linked. 

-ddest  Select  dest  as  the  printer  or  class  of  printers  that  is  to  do  the  printing.  If  dest  is  a  printer, 

the  request  will  be  printed  only  on  that  specific  printer.  If  dest  is  a  class,  the  request  will 
be  printed  on  the  first  avail  able  printer  that  is  a  member  of  the  class.  Under  certain  condi- 
tions (printer  unavailability,  file  space  limitation,  etc.),  requests  for  a  specific  dest  might  not 
be  accepted  (see  accept(lM)  and  Ipadmin(lM)). 

If  the  -d  option  is  omitted,  dest  is  taken  from  the  environment  variable  LPDEST.  If  that 
variable  is  unset  or  empty,  the  default  queue  is  used,  if  one  has  been  defined.  If  there  is  no 
default  queue,  or  LPDEST  is  set  but  invalid,  lp  issues  an  error  message  and  the  request  is 
not  queued.  Printer  and  class  names  and  the  default  queue  are  defined  by  your  LP  subsys- 
tem administrator  (see  Ipadmin(lM)  and  Ipstat(l)). 

-m  Send  a  mail  message  (see  mail(l)).  to  the  user  after  the  request  has  been  printed.  By 

default,  no  mail  is  sent  upon  normal  completion  of  the  print  request. 

-nnumber       Print  number  copies  of  the  output.  The  default  is  1. 

-ooption         Specify  a  printer-dependent  option.  You  can  specify  several  printer  options  by  repeating 
the  -o  option.  For  information  about  the  options  that  are  availablefor  a  printer  supported 
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on  your  system,  see  the  interface  script  for  the  printer  name  in  the 
/etc/lp/interface  directory. 

-ppriority  Set  the  priority  of  the  print  request,  priority  must  be  in  the  range  0  (lowest  priority)  to  7 
(highest  priority).  The  priority  is  used  to  select  the  next  spooled  file  for  the  targeted 
printer  or  class  of  printers.  If  the  priority  is  less  than  the  fence,  the  minimum  priority  set 
for  the  printer,  the  print  request  is  deferred  until  the  fence  is  lowered  or  the  priority  is 
raised.  The  default  for  a  printer  queue  is  the  default  priority  set  by  the  lpadmin  or 
lpfence  command  (see  Ipadmin(lM)  and  Ipsched(lM)).  The  default  for  a  class  queue  is 
the  highest  default  priority  among  printers  in  the  class. 

-s  Suppress  standard  output  messages  from  lp  such  as  "request  id  is        Error  mes- 

sages are  still  displayed  on  standard  error. 

-ttitle  Print  title  on  the  banner  page  of  the  output. 

-w  Write  a  message  to  the  user's  terminal  after  the  request  has  been  printed.  If  the  user  is 

not  logged  in  or  (for  remote  printing)  if  rlpdaemon  (see  rlpdaemon(lM))  is  not  running 
on  the  user's  local  system,  mail  will  be  sent  instead. 

Ipalt  Command 

The  lpalt  command  alters  a  request  made  by  a  previous  lp  command,  if  it  is  not  currently  printing.  (To 
requeue  a  currently  printing  request,  use  the  disable  command  (see  enabled))  to  stop  the  printer.) 

Ipalt  Options 

lpalt  recognizes  the  following  options  and  arguments,  which  can  be  specified  in  any  order.  Blanks  are 
not  permitted  between  a  keyletter  and  its  argument. 

id  Specifies  the  request  to  be  altered,  id  is  a  request  id  returned  by  lp  or  lpalt. 

-ddest  Requeue  the  request  to  the  named  printer  or  class  dest.  A  new  unique  request  id  is  written 

to  standard  output. 

-i  Alter  only  local  requests. 

-m  Send  mail  upon  normal  completion  of  the  print  request, 

-nnumber       Change  the  number  of  copies  to  number. 

-ooption  Specify  a  printer-dependent  option.  You  can  specify  several  printer  options  by  repeating 
the  -o  option.  All  -o  options  from  previous  lp  and  lpalt  commands  for  this  request  id 
are  deleted. 

-ppriority       Change  the  request's  priority  to  priority. 

-s  Suppress  standard  output  messages  from  lpalt  such  as  "request  id  is  Error 

messages  are  still  displayed  on  standard  error. 

-ttitle  Change  the  titleon  the  banner  page  of  the  output. 

-w  Write  a  message  to  the  user's  terminal  after  the  request  has  been  printed.  If  the  user  is 

not  logged  in  or  (for  remote  printing)  if  rlpdaemon  (see  rlpdaemon (1M)).  is  not  running 
on  the  user's  local  system,  mail  will  be  sent  instead. 

cancel  Command 

The  cancel  command  cancels  requests  that  were  made  with  the  lp  command,  even  if  they  are  currently 
printing.  At  least  one  id  or  printer  must  be  specified. 

The  cancellation  of  a  request  that  is  currently  printing  frees  the  printer  to  print  its  next  avail  able  request. 

cancel  Options  and  Arguments 

cancel  recognizes  the  following  options  and  arguments,  which  can  be  specified  in  any  order.  Blanks  are 
not  permitted  between  a  keyletter  and  its  argument. 

id  ...  Specifies  one  or  more  requests,  id  is  a  request  id  returned  by  lp  or  lpalt. 

printer  ...  Specifies  one  or  more  printers,  printer  is  the  name  of  a  printer,  not  a  class.  Either  cancel 
the  request  that  is  currently  printing  on  each  printer,  or,  if  an  -a,  -e,  or  -u  option  is 
specified,  specify  the  printer  on  which  to  perform  the  corresponding  operation. 
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-a  Remove  all  requests  the  user  owns  on  each  printer.  The  owner  is  determined  by  the  user's 

login  name  and  the  host  name  of  the  machine  where  the  lp  command  was  invoked. 

-e  Empty  the  spool  queue  of  all  requests  for  each  printer.  Only  users  with  appropriate 

privileges  can  use  this  option. 

-i  Cancel  only  local  requests. 

-uuser  Remove  any  requests  belonging  to  user.  You  can  repeat  the  -u  option  to  specify  more 

users.  Only  users  with  appropriate  privileges  can  use  this  option. 

Printing  Overview 

A  printer  can  print  requests  from  one  or  two  destination  queues:  its  own  private  queue  and  an  optional 
class  queue,  which  can  serve  one  or  more  printers.  The  destination  queues  are  set  up  with  the  lpadmin 
command.  The  lp  command  places  a  printing  request  into  a  printer  or  class  destination  queue  as  directed 
by  a  user.  The  lpsched  scheduler  directs  the  requests  from  the  destination  queues  to  the  printers.  The 
accept  and  reject  commands  control  whether  lp  can  place  requests  in  the  destination  queues.  The 
enable  and  disable  commands  control  whether  lpsched  can  send  a  queued  request  to  a  printer.  If  a 
printer  has  two  queues  and  one  queue  is  rejecting  requests,  users  can  still  direct  requests  to  the  other  desti- 
nation queue  and  have  the  requests  printed,  lpstat  reports  the  current  status  of  the  destination  queues 
and  the  scheduler.  See  enabled),  Ipstat(l),  accept(lM),  and  Ipadmin(lM). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  set  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used. 

LC_ALL  determines  the  locale  to  use  to  override  any  values  for  locale  categories  specified  by  the  setti ng  of 
LANG  or  any  environment  variables  beginning  with  LC_. 

LC_CTYPE  determines  the  locale  for  interpretation  of  sequences  of  bytes  of  text  data  as  characters  (e.g., 
single-  verses  multibyte characters  in  arguments  and  input  files). 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

LPDEST  determines  the  output  device  or  destination.  If  the  LPDEST  environment  variable  is  not  set,  the 
PRINTER  environment  variable  is  used.  The  -d  dest  option  takes  precedence  over  LPDEST.  Results  are 
undefined  when  -d  is  not  specified  and  LPDEST  contains  a  value  that  is  not  a  valid  device  or  destination 
name. 

PRINTER  determines  the  output  device  or  destination.  If  the  LPDEST  and  PRINTER  environment  vari- 
ables are  not  set,  an  unspecified  output  device  is  used.  The-d  dest  option  and  the  LPDEST  environment 
variable  takes  precedence  over  PRINTER.  Results  are  undefined  when  -d  is  not  specified,  LPDEST  is 
unset,  and  PRINTER  contains  a  value  that  is  not  a  valid  device  or  destination  name. 

If  any  internationalization  variable  contains  an  invalid  setting,  the  commands  behave  as  if  all  international- 
ization variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

RETURN  VALUE 

Exit  values  are: 

0    Successful  completion. 
>0    Error  condition  occurred. 

EXAMPLES 

For  a  HP2934A  printer  named  lp2,  configured  with  an  interface  script  that  defines  the  -c  option  to  cause 
the  printer  to  print  in  a  compressed  mode,  use  the  following  command  to  print  myf  ile  with  compressed 
print  on  lp2: 

lp  -dlp2  -oc  myfile 

lp  can  be  used  at  the  end  of  a  pipeline  to  print  the  results  of  a  previous  command.  It  is  commonly  used 
with  the  pr  command  (see  pr(l))  to  print  formatted  output.  For  a  default  printer,  to  format  file  .pro- 
file into  pages  and  print  three  copies  of  it: 
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pr   .profile    |   lp  -n3 


WARNINGS 


A  remote  print  request  can  be  altered  or  canceled  only  by  the  user  who  requested  it,  and  only  from  the  sys- 
tem from  which  the  the  original  lp  command  was  issued. 

If  the  restrict  cancel  feature  (see  Ipadmin(lM))  is  enabled  for  the  specified  printer,  a  user  can  only  alter  or 
cancel  requests  owned  by  the  user. 

For  a  remote  system,  lpalt  cannot  change  dest  and  priority. 


enabled),  Ipstat(l),  mail(l),  slp(l),  accept(lM),  Ipadmin(lM),  Ipana(lM),  Ipsched(lM),  rcancel(lM),  rlp(lM), 
rlpdaemon(lM),  rlpstat(lM). 

STANDARDS  CONFORMANCE 

lp:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 

cancel:  SVID2,  SVID3,  XPG4 


FILES 


/etc/lp 

/etc/ lp/ interface 
/usr/lib/lp 
/var/adm/lp 
/var/ spool/lp 


Directory  of  spooler  configuration  data 
Directory  of  activeLP  device  interface  scripts 
Directory  of  model  and  font  file  directories 
Directory  of  spooler  log  files 
Directory  of  LP  spooling  files  and  directories 


SEE  ALSO 
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NAME 

Ipfilter,  divpage,  fontdl,  Iprpp,  plotdvr,  printstat,  reverse  -  filters  invoked  by  Ip  interface  scripts 
SYNOPSIS 

/usr/lbin/divpage  [-p  I  -1]  [-h  |  -q]  [-nFontID]  filename 
/usr/lbin/fontdl  [-nFontID]  [-1]  [-p]  filename 
/usr/lbin/lprpp  [-i]  [-o]  [-e]  [-Inn  ]  [-n]  [-p] 
/usr/lbin/plotdvr  -lrequestid  -uusername  [-e]  [-f]  [-i]  filename 
/usr/sbin/printstat  -lrequest  id  -u username  filename 
/usr/sbin/reverse  [-1  page  length] 

Remarks 

The  structure  of  these  filters  is  currently  under  review.  They  may  become  obsolete  or  be  restructured  in  a 
future  release. 

DESCRIPTION 

Various  filters  are  used  by  the  lp  subsystem  to  obtain  specialized  behavior  for  specific  types  of  devices  or 
data.  This  entry  describes  currently  supported  filters. 

A  number  of  these  filters  use  a  specified  username  and  filename  to  determine  the  location  of  the  user  who 
originated  the  print  message. 

The  filename  is  used  to  determine  the  hostname  of  the  system  where  the  request  originated,  and  must  have 
the  form  [dirname]/d?Annnhostname  or  [dirname]/dAnnnnhostname,  where  dirname  is  not  a  path 
name,  but  only  the  name  of  the  basename's  parent  directory,  filename  meets  this  requirement  when  it  is 
set  to  $6  in  the  i nterface scri pt  for  the  printer. 

divpage 

Provides  capabilities  for  printing  multiplepages  per  sheet  and  selection  of  built-in  fonts. 
Options: 

-p  Set  mode  to  portrait  (default). 

-1  Set  mode  to  landscape, 

-h  Print  half  pages  (default), 

-q  Print  quarter  pages. 

-nFontID       U  se  font  number  Fontl  D.  Default  isO.  Causes  the  string  Ec  ( Fontmx  to  be  sent  to  the 
printer. 

fontdl 

fontdl  downloads  the  font  contained  in  filename  to  a  printer  connected  to  standard  output. 
Options: 

-nFontID       Specifies  the  I D  number  by  which  the  font  will  be  referenced.  DefaultisO. 
-1  Specify  landscape  mode.  Default  is  portrait, 

-p  Specifies  proportional  spacing.  Default  is  fixed. 

Iprpp 

This  is  a  filter  that  converts  backspace  overstrike  to  line  overprint  with  horizontal  print  positioning  to 
enhance  bold  print.  This  functionality  is  required  on  printers  such  as  the  LaserJ  et,  which  cannot  produce 
bold  print  by  overstriking. 

Options: 

-i  Converts  <ANYCHAR>  to  <ANYCHARxBACKSPACE>_  to  italicize  ANYCHAR. 

Also  properly  italicizes  overstruck  (bold)  characters.  Does  not  work  correctly  for 
"hashed-overstrike"  such  as: 

<ANYCHARxBACKSPACExDI  FFERENTCHARxBACKSPACE> 
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-o 
-e 

-1  nn 


Prints  only  the  odd  numbered  pages.  Used  with 
Print  only  the  even  numbered  pages.  Used  with 


-e  for  double-sided  printing, 
-o  for  double  sided  printing. 


Specifies  the  page  length,  in  lines.  Default  is  60  unless  -n  or  -p  is  selected,  in  which 
case  it  is  66. 

-n  Specifies  nroff  mode  for  printing  output  of  the  nroff  command.  Prints  66  lines  per 

page  with  the  first  line  appearing  on  logical  line  4  of  the  printer. 

-p  Specifies  pr  mode  for  printing  output  from  the  pr  command.  Prints  66  lines  per  page 

with  the  first  line  appearing  on  logical  line  3  of  the  printer. 

plotdvr 

HP-GL  plotter  filter.  This  filter  scans  the  data  for  "PG"  commands  (paper  feed).  When  this  data  is  encoun- 
tered, the  filter  strips  it  from  the  data  stream  and  informs  the  requesting  user  of  the  need  to  change  paper 
in  the  plotter. 


Options: 

-1  requestid 

-u  username 


-f 


Specifies  the  printer  request  ID  and  is  used  in  various  messages  regarding  the  plot 
request. 

The  requesting  user's  login  name,  used  to  communicate  with  the  user  regarding  the 
request. 

Specifies  the  use  of  escape  sequences,  rather  than  HP-GL  commands,  to  determine 
plotter  status. 

Plot  without  stopping  for  paper  changes.  The  "PG"  commands  are  not  stripped  from 
the  data  stream  and  the  user  is  not  notified  of  them.  This  option  is  used  on  plotters 
capable  of  automatic  page  feed. 

-i  Prevents  initialization  of  the  plotter, 

printstat 

I  nterrogates  an  RS232  printer  as  to  its  status,  and  does  not  return  until  the  printer  is  ready.  If  the  printer 
is  off-line,  out  of  paper,  or  disconnected,  the  submitter  of  the  print  request  is  notified  of  this  condition 
periodically  until  it  is  corrected.  When  the  printer  is  ready  to  print,  the  command  exits. 

Standard  input  and  standard  output  must  both  be  connected  to  the  serial  printer  device. 

This  program  uses  the  send-status  command  Ec?Di?  to  determine  status.  Not  all  serial  printers  respond 
to  this  command.  Only  the  foil  owing  configurations  support  this  command: 


Printer 

Comments 

LaserJ  et 
LaserJ  etll 
LaserJ  etllD 
LaserJ  etllP 
LaserJ  etlll 
LaserJ  et2000 

Not  supported 
Supported 

Requires  hp  26013A  module 
Not  supported 
Requires  hp  26013A  module 
Not  supported 

Options: 

-1  request-id    Print  request  I D  used  in  various  communications  with  the  user. 

-u username    The  requesting  user's  login  name,  used  to  communicate  with  the  user  regarding  the 
request. 

reverse 

Prints  the  data  appearing  on  the  standard  input  in  reverse  page  order  to  the  standard  output.  This  com- 
mand can  handle  up  to  2000  pages. 


Options : 

-1  pagelength 


Specifies  the  page  length,  in  lines.  Default  is  66. 
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DIAGNOSTICS 

Error  and  diagnostic  messages  appear  on  the  printed  output,  on  the  user's  terminal,  or  are  mailed  to  the 
user,  depending  on  circumstances. 

WARNINGS 

There  is  littleconsistency  in  the  interface  to  these  filters. 

SEE  ALSO 

lp(l),  Ipadmin(lM). 

Managing  Systems  and  Workgroups. 
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NAME 

Ipstat-  report  line  printer  status  information 
SYNOPSIS 

Ipstat  [-drst]  [-a[list]]  [-c[list]]  [-©[list]]  [-p[list]]  [-u[list]]  [-v[list]]  [ID...] 
DESCRIPTION 

The  Ipstat  utility  writes  to  standard  output  information  about  the  current  status  of  the  line  printer  sys- 
tem. 

If  no  arguments  are  given,  Ipstat  writes  the  status  of  all  requests  made  to  lp  by  the  user  that  are  still 
in  the  output  queue. 

OPTIONS 

The  Ipstat  utility  supports  the  XBD  specification,  Section  10.2,  Utility  Syntax  Guidelines,  except  the 
option-arguments  are  optional  and  cannot  be  presented  as  separate  arguments. 

Some  of  the  options  below  can  be  followed  by  an  optional  list  that  can  be  in  one  of  two  forms:  a  list  of  items 
separated  from  one  another  by  a  comma,  or  a  quoted  list  of  items  separated  from  one  another  by  a  comma 
or  one  or  more  blank  characters,  or  combinations  of  both.  See  EXAMPLES. 

The  omission  of  a  list  following  such  options  causes  all  information  relevant  to  the  option  to  be  written  to 
standard  output;  for  example: 

Ipstat  -o 

writes  the  status  of  all  output  requests  that  are  still  in  the  output  queue. 

-a[list]      Write  the  acceptance  status  of  destinations  for  output  requests.  The  list  argument  is  a 
list  of  intermixed  printer  names  and  class  names. 

-c[list]      Write  the  class  names  and  their  members.  The  list  argument  is  a  list  of  class  names. 

-d  Write  the  system  default  destination  for  output  requests. 

— o [ I i st ]      Write  the  status  of  output  requests.  The  list  argument  is  a  list  of  intermixed  printer 
names,  class  names  and  request  I  Ds. 

— p  [  I  i  st  ]      Write  the  status  of  printers.  Thelist  argument  isa  list  of  printer  names. 

-r  Write  the  status  of  the  line  printer  request  scheduler. 

-s  Write  a  status  summary,  including  the  status  of  the  line  printer  scheduler,  the  system 

default  destination,  a  list  of  class  names  and  their  members  and  a  list  of  printers  and 
their  associated  devices. 

-t  Write  all  status  information. 

-u[list]      Write  the  status  of  output  requests  for  users.  The  list  argument  is  a  list  of  login  names. 

-v[list]      Write  the  names  of  printers  and  the  pathnames  of  the  devices  associated  with  them.  The 
list  argument  isa  list  of  printer  names. 

OPERANDS 

The  foil  owing  operand  is  supported: 

ID  A  request  I D,  as  returned  by  lp. 

STDIN 

Not  used. 

INPUT  FILES 

None. 

ENVIRONMENT  VARIABLES 

The  foil  owing  environment  variables  affect  the  execution  of  Ipstat: 

LANG  Provide  a  default  value  for  the  internationalisation  variables  that  are  unset 

or  null.  If  LANG  is  unset  or  null,  the  corresponding  value  from  the 
implementation-specific  default  locale  will  be  used.  If  any  of  the  interna- 
tionalisation variables  contains  an  invalid  setting,  the  utility  will  behave  as 
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if  none  of  the  variables  had  been  defined. 

LC_ALL  If  set  to  a  non-empty  string  value,  override  the  values  of  all  the  other  inter- 

nationalisation  variables. 

LC_CTYPE  Determine  the  locale  for  the  interpretation  of  sequences  of  bytes  of  text 

data  as  characters  (for  example,  single-  as  opposed  to  multi-byte  characters 
in  arguments). 

LC_ME S SAGE S  Determine  the  locale  that  should  be  used  to  affect  the  format  and  contents 

of  diagnostic  messages  written  to  standard  error,  and  informative  messages 
written  to  standard  output. 

LC_TIME  Determine  the  format  of  date  and  time  strings  output  when  displaying  line 

printer  status  information  with  the -a,  -o,  -p,  -t,  or  -u  options. 

NLSPATH  Determine  the  location  of  message  catalogues  for  the  processing  of 

LC_MESSAGES. 

TZ  Determine  the  timezone  used  with  date  and  time  strings. 

ASYNCHRONOUS  EVENTS 

Default. 

STDOUT 

The  standard  output  is  a  text  file  containing  the  information  described  in  OPTIONS,  in  an  unspecified  for- 
mat. 

STDERR 

Used  only  for  diagnostic  messages. 

OUTPUT  FILES 

None. 

EXTENDED  DESCRIPTION 

None. 

EXIT  STATUS 

The  foil  owing  exit  values  are  returned: 

0     Successful  completion. 
>0    An  error  occurred. 

CONSEQUENCES  OF  ERRORS 

Default. 

APPLICATION  USAGE 

Thelpstat  utility  cannot  reliably  determine  the  status  of  print  requests  in  all  conceivable  circumstances. 
When  the  printer  is  under  the  control  of  another  operating  system  or  resides  on  a  remote  system  across  a 
network,  it  need  not  be  possible  to  determine  the  status  of  the  print  job  after  it  has  left  the  control  of  the 
local  operating  system.  Even  on  local  printers,  spooling  hardware  in  the  printer  may  make  it  appear  that 
the  print  job  has  been  completed  long  before  the  final  page  is  printed. 

EXAMPLES 

1.  Obtain  the  status  of  two  printers,  the  pathnames  of  two  printers,  a  list  of  all  class  names  and  the 
status  of  the  request  named  HiPri-33: 

lpstat  -plaserl , laser4  -v"laser2   laser3"   -c  HiPri-33 

2.  Obtain  user  print  job  status  using  the  obsolescent  mixed  blank  and  comma  form: 

lpstat  -u"ddg,gmv,  maw" 

FUTURE  DIRECTIONS 

A  version  of  lpstat  that  fully  supports  the  XBD  specification,  Section  10.2,  Utility  Syntax  Guidelines  may 
be  introduced  in  a  future  issue. 
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SEE  ALSO 

cancel(l),  lp(l). 

CHANGE  HISTORY 

F  i  rst  rel eased  i  n  I  ssue  2. 

Issue  3 

The  operation  of  this  utility  in  an  8-bit  transparent  manner  has  been  noted. 
Theoperation  of  this  utility  in  an  internationalised  environment  has  been  described. 

I  ssue  4 

Format  reorganised. 

Exceptions  to  Utility  Syntax  Guidelines  conformance  noted. 
Internationalised  environment  variable  support  mandated. 

STANDARDS  CONFORMANCE 

lpstat :  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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DESCRIPTION 

Any  arguments  that  are  not  options  are  assumed  to  be  request  ids  (as  returned  by  lp).  lpstat  prints 
the  status  of  such  requests,  options  can  appear  in  any  order  and  can  be  repeated  and  intermixed  with 
other  arguments. 


Security  Restriction 

Only  users  who  have  the  lp  subsystem  authorization  or  the  printqueue  secondary  subsystem  authori- 
zation can  view  the  entire  queue.  Unauthorized  users  can  view  only  their  own  jobs  whose  sensitivity  levels 
are  dominated  by  the  user's  current  sensitivity  level. 

The  allowmacaccess  privilegeallows  viewingjobs  at  higher  sensitivity  levels. 

EXAMPLES 

Check  whether  your  job  is  queued: 

lpstat 

Check  the  relative  position  of  a  queued  job: 

lpstat  -t 
Verify  that  thejob  scheduler  is  running: 

lpstat  -r 

FILES 

/var/ spool/lp/* 
/ var/ adm/ lp/ * 
/etc/lp/* 
/usr/lib/lp/* 

SEE  ALSO 

enabled),  Ipd),  rlpstat(lM). 

STANDARDS  CONFORMANCE 

lpstat :  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 


-t 


-i 


-o[list] 


I  nhibit  the  reporting  of  remote  status. 
Also  see  the  -i  option. 

Print  all  status  information.  Same  as  specifying  -r,  -s,  -a,  -p,  -o.  See  the  -i 
option. 


HP-UX  Release  Hi:  December  2000 


-1- 


Section  1-479 


Is(l) 


ls(l) 


NAME 

Is,  Ic,  I,  II,  Isf,  Isr,  Isx  -  list  contents  of  directories 
SYNOPSIS 

Is  [-abcdefgilmnopqrstuxACFLRl]  [names] 
lc  [-abcdefgilmnopqrstuxACFLRl]  [names] 

I  [Isoptions]  [names] 

II  [Is  options]  [names] 
lsf  [Is  options]  [names] 
lsr  [Is  options]  [names] 
lsx  [Is  options]  [names] 

DESCRIPTION 

For  each  directory  argument,  the  Is  command  lists  the  contents  of  the  directory.  For  each  file  argument, 
Is  repeats  its  name  and  any  other  information  requested.  The  output  is  sorted  in  ascending  collation  order 
by  default  (see  Environment  Variables  below).  When  no  argument  is  given,  the  current  directory  is  listed. 
When  several  arguments  are  given,  the  arguments  are  first  sorted  appropriately,  but  file  arguments  appear 
before  directories  and  their  contents. 

If  you  are  a  user  with  appropriate  privileges,  all  files  except  .  and  .  .  are  listed  by  default. 

There  are  three  major  listing  formats.  The  format  chosen  depends  on  whether  the  output  is  going  to  a 
login  device  (determined  by  whether  output  device  file  is  a  tty  device),  and  can  also  be  control  led  by  option 
flags.  The  default  format  for  a  login  device  is  to  list  the  contents  of  directories  in  multi column  format,  with 
entries  sorted  vertically  by  column.  (When  individual  file  names  (as  opposed  to  directory  names)  appear  in 
the  argument  list,  those  file  names  are  always  sorted  across  the  page  rather  than  down  the  page  in  columns 
because  individual  file  names  can  be  arbitrarily  long.)  If  the  standard  output  is  not  a  login  device,  the 
default  format  is  to  list  one  entry  per  line.  The-C  and  -x  options  enable  multi  column  formats,  and  the  -m 
option  enables  stream  output  format  in  which  files  are  listed  across  the  page,  separated  by  commas.  In 
order  to  determine  output  formats  for  the  -C,  -x,  and  -m  options,  Is  uses  an  environment  variable, 
COLUMNS,  to  determine  the  number  of  character  positions  availableon  each  output  line.  If  this  variableis 
not  set,  the  terminf  o  database  is  used  to  determine  the  number  of  columns,  based  on  the  environment 
variable  TERM.  If  this  information  cannot  be  obtained,  80  columns  is  assumed. 

The  command  lc  functions  the  same  as  Is  except  that  the  lc  default  output  is  columnar,  even  if  output  is 
redirected. 

Options 

Is  recognizes  the  following  options: 

-a    List  all  entries;  usually  entries  whose  names  begin  with  a  period  ( . )  are  not  listed, 
-b    List  nonprinting  characters  in  the  octal  \ddd  notation. 

-c  Use  time  of  last  modification  of  the  inode  (file  created,  mode  changed,  etc.)  for  sorting  (-t)  or 
printing  (-1  (ell)). 

-d  If  an  argument  is  a  directory,  list  only  its  name  (not  its  contents);  often  used  with  -1  (ell)  to  get 
the  status  of  a  directory. 

-e  List  the  extent  attributesof  the  file.  If  any  of  the  files  has  a  extent  attribute,  this  option  liststhe 
extent  size,  space  reserved  and  allocation  flags.  This  option  must  be  used  with  the  -1  (ell) 
option. 

-f  Interpret  each  argument  as  a  directory  and  list  the  name  found  in  each  slot.  This  option  disables 
-1  (ell),  -r,  -s,  and  -t,  and  enables  -a;  the  order  is  the  order  in  which  entries  appear  in  the 
directory. 

-g  Same  as  -1  (ell),  except  that  only  the  group  is  printed  (owner  is  omitted).  If  both  -1  (ell)  and 
-g  are  specified,  the  owner  is  not  printed. 

-i  For  each  file,  list  the  inode  number  in  the  first  column  of  the  report.  When  used  in  multicolumn 
output,  the  number  precedes  the  file  name  in  each  column. 

-1  (ell)  List  in  long  format,  giving  mode,  number  of  links,  owner,  group,  size  in  bytes,  and  time  of 
last  modification  for  each  file  (see  further  DESCRIPTION  and  Access  Control  Lists  below).  If  the 
time  of  last  modification  is  greater  than  six  months  ago,  or  any  time  in  the  future,  the  year  is 
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substituted  for  the  hour  and  minute  of  the  modification  time.  If  the  file  is  a  special  file,  the  size 
field  contains  the  major  and  minor  device  numbers  rather  than  a  size.  If  the  file  is  a  symbolic 
link,  the  filename  is  printed,  followed  by  ->  and  the  pathname  of  the  referenced  file. 

-m   Stream  output  format. 

-n  Thesameas-1,  (ell)  except  that  the  owner's  Ul  D  and  group's  GID  numbers  are  printed,  rather 
than  the  associated  character  strings. 

-o  The  same  as  -1,  (ell)  except  that  only  the  owner  is  printed  (group  is  omitted).  (If  both  -1  (ell) 
and  -o  are  specified,  the  group  is  not  printed). 

-p    Put  a  slash  (/)  after  each  file  name  if  that  file  is  a  directory. 

-q   List  nonprinting  characters  in  file  names  as  the  character  (?). 

-r    Reverse  the  order  of  sort  to  get  reverse  (descendi  ng)  col  lation  or  oldest  first,  as  appropriate. 

-s  List  size  in  blocks,  including  indirect  blocks,  for  each  entry.  The  first  entry  listed  is  the  total 
number  of  blocks  in  the  directory.  When  used  in  multicolumn  output,  the  number  of  blocks  pre- 
cedes the  file  name  in  each  column.  The  number  of  indirect  blocks  in  a  file  is  filesystem  depen- 
dent. 

-t    Sort  by  time  modified  (latest  first)  before  sorting  alphabetically. 

-u  Use  time  of  last  access  instead  of  last  modification  for  sorting  (-t  option)  or  printing  (-1  (ell) 
option). 

-x    List  multicolumn  output  with  entries  sorted  across  rather  than  down  the  page. 

-A  The  same  as -a,  except  that  the  current  directory  .  and  parent  directory  ..  are  not  listed.  For 
a  user  with  appropriate  privileges,  this  flag  defaults  to  on,  and  isturned  off  by -A. 

-C    List  multicolumn  output  with  entries  sorted  down  the  columns. 

-F   After  each  file  name,  put  one  of: 

•  A  slash  (/)  if  the  file  is  a  directory  or  a  symbolic  link  to  a  directory. 

•  An  asterisk  (*)  if  the  file  is  executable; 

•  An  at-sign  (@)  if  the  file  is  a  symbolic  link  to  a  file; 

•  A  vertical  bar  ( | )  if  the  file  is  a  fifo. 

-L  If  the  argument  is  a  symbolic  link,  list  the  file  or  directory  to  which  the  link  refers  rather  than 
the  link  itself. 

— R   Recursively  list  subdirectories  encountered. 

-1  (one)  List  the  file  names  in  single  column  format  regardless  of  the  output  device.  This  forces  sin- 
gle column  format  to  the  user's  terminal. 

Specifying  more  than  one  of  the  options  in  the  foil  owing  mutually  exclusive  pairs  is  not  considered  an  error: 
-C  and  -1  (ell),  -m  and  -1  (ell),  -x  and  -1  (ell),  -C  and  -1  (one),  and  -c  and  -u. 

Is  is  known  by  several  shorthand-version  names  for  the  various  formats: 

I  is  equivalent  to  Is -m 

II  is  equivalent  to  Is -1  (ell) 
lsf  is  equivalent  to  Is  — F 
lsr  is  equivalent  to  Is  -R 
lsx  is  equivalent  to  Is  -x 

The  shorthand  notations  are  implemented  as  links  to  Is.  Option  arguments  to  the  shorthand  versions 
behave  exactly  as  if  the  long  form  above  had  been  used  with  the  additional  arguments. 

Mode  Bits  Interpretation  (-1  option) 

The  mode  printed  in  listings  produced  by  the  -1  (ell)  option  consists  of  10  characters,  for  example, 
-rwxr-xr-x. 

The  first  character  indicates  the  entry  type: 

b     Block  special  file 
c     Character  special  file 
d  Directory 

H  P-UX  Release  Hi :  December  2000  -  2  -  Section  1-481 


Is(l) 


ls(l) 


1     Symbolic  link 

n     Network  special  file 

p     Fifo  (also called  a  "named  pipe")  special  file 

s  Socket 

Ordinary  file 

The  next  9  characters  are  interpreted  as  three  sets  of  three  characters  each  which  identify  access  and  exe- 
cution permissions  for  the  owner,  group,  and  others  categories,  as  described  in  chmod(l).  The  -  indicates 
the  permission  is  not  granted.  The  various  permissions  can  be  put  together  in  any  combination,  except  that 
thex,  s,  S,  t,  and  T  characters  are  mutually  exclusive,  as  implied  below. 


-r  Read  by  owner 

— w  Write  by  owner 

 x  Execute  (or  search  directory)  by  owner;  do  not  set  user  I D  on  execution 

 s  Execute/search  by  owner;  set  user  I D  on  execution 

 S  No  execute/search  by  owner;  set  user  I D  on  execution 

 r  Read  by  group 

 w  Write  by  group 

 x  Execute/search  by  group;  do  not  set  group  I D  on  execution 

 s  Execute/search  by  group;  set  group  I D  on  execution 

 S  No  execute/search  by  group;  set  group  I D  on  execution 

 r —  Read  by  others 

 w-  Write  by  others 

 x  Execute/search  by  others;  do  not  set  sticky  bit  on  execution 

 1  Execute/search  by  others;  set  sticky  bit  on  execution 

 T  No  execute/search  by  others;  set  sticky  bit  on  execution 


The  mode  characters  are  interpreted  as  follows: 

Deny  all  permissions  in  the  corresponding  position, 
r     Grant  read  permission  to  the  corresponding  user  class, 
w     Grant  write  permission  to  the  corresponding  user  class. 

x     Grant  execute  (or  search  in  directory)  permission  to  the  corresponding  user  class. 

s     Grant  execute  (search)  permission  to  the  corresponding  user  class.  Execute  the  file  as  if  by  the 
owner  (set  user  ID,  SUID)  or  group  (set  group  ID,  SGID),  as  indicated  by  position. 

S     Deny  execute  (search)  permission  to  the  corresponding  user  class.  Execute  the  file  as  if  by  the 
owner  (set  user  I D,  SUI D)  or  group  (set  group  I D,  SGI  D),  as  indicated  by  position. 

t     Grant  execute  (search)  permission  to  others.  The  "sticky"  (save  text  image)  bit  is  set  (see  the 
description  of  S_ISVTX  in  chmod(2)). 

T     Deny  execute  (search  directory)  permission  to  others.  The  "sticky"  (save  text  image)  bit  is  set. 

When  an  option  is  specified  that  results  in  a  listing  of  directory  and/or  file  sizes  in  bytes  or  blocks  (such  as 
the  -s  or  -1  (ell)  option),  a  total  count  of  blocks,  including  indirect  blocks,  is  also  printed  at  the  beginning 
of  the  listing. 

Access  Control  Lists  (ACLs) 

If  a  file  has  optional  ACL  entries,  the  -1  (ell)  option  displays  a  plus  sign  (+)  after  the  file's  permissions. 
The  permissions  shown  are  a  summary  representation  of  the  file's  access  control  list,  as  returned  by 
stat  ()  in  the  st_mode  field  (see  stat(2)).  To  list  the  contents  of  an  access  control  list,  use  the  lsacl 
command  (see  lsacl  (1)  and  acl(5))  for  HFS  file  systems,  or  thegetacl  command  (seegetacl  (1)  and  aclv(5)) 
for  J  FS  file  systems. 

EXTERNAL  INFLUENCES 
Environment  Variables 

If  the  COLUMNS  variable  is  set,  Is  uses  the  width  provided  in  determining  positioning  of  columnar  output. 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  set  or  is  null,  it  defaults 
toC  (see  lang(5)). 

LC_COLLATE  determines  the  order  in  which  the  output  is  sorted. 
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LC_CTYPE  determines  which  characters  are  classified  as  nonprinting  for  the  -b  and  -q  options,  and  the 
interpretation  of  single- and/or  multibyte  characters  within  file  names. 

LC_TIME  determines  the  date  and  time  strings  output  by  the  -g,  -1  (ell),  -n,  and  -o  options. 

LC_ME S SAGE S  determines  the  language  in  which  messages  (other  than  the  date  and  time  strings)  are 
displayed. 

If  any  internationalization  variable  contains  an  invalid  setting,  they  all  default  to  C  (see  environ  (5)). 

I  nternational  Code  Set  Support 

Single-  and  multibyte  character  code  sets  are  supported. 

RETURN  VALUE 

Is  exits  with  one  of  the  foil  owing  values: 

0   All  input  files  were  listed  successfully. 

>0    Is  was  aborted  because  errors  occurred  when  accessing  files.  The  following  conditions  cause  an 
error: 

•  Specified  file  not  found. 

•  User  has  no  permission  to  read  the  directory. 

•  Process  could  not  get  enough  memory. 

•  Invalid  option  specified. 

EXAMPLES 

Print  a  long  listing  of  all  the  files  in  the  current  working  directory  (including  the  file  sizes).  List  the  most 
recently  modified  (youngest)  file  first,  followed  by  the  next  older  file,  and  so  forth,  to  the  oldest.  Files 
whose  names  begin  with  a  .  are  also  printed. 

Is  -alst 
WARNINGS 

Setting  options  based  on  whether  the  output  is  a  login  (tty)  device  is  undesirable  because  Is  -s  is  very 
different  from  Is -s  |  lp.  On  the  other  hand,  not  using  this  setting  makes  old  shell  scripts  that  used  Is 
almost  inevitably  fail. 

Nonprinting  characters  in  file  names  (without  the  -b  or  -q  option)  may  cause  columnar  output  to  be 
misaligned. 

DEPENDENCIES 
NFS 

The  -1  (ell)  option  does  not  display  a  plus  sign  (+)  after  the  access  permission  bits  of  networked  files  to 
represent  existence  of  optional  access  control  list  entries. 

AUTHOR 

Is  was  developed  by  AT&T,  the  University  of  California,  Berkeley  and  HP. 
FILES 

/etc/group  For  group  IDs  for  -1  (ell)  and  -g. 

/etc/passwd  For  user  IDs  for  -1  (ell)  and  -o. 

/usr/share/lib/terminf  o/?/*    For  terminal  information. 

SEE  ALSO 

chmod(l),  find(l),  getacl(l),  Isacl(l),  stat(2),  acl(5),  aclv(5). 

STANDARDS  CONFORMANCE 

Is:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

Isacl  -  list  access  control  lists  (ACLs)  of  files 

SYNOPSIS 

/usr/bin/lsacl  [-1]  file... 

DESCRIPTION 

lsacl  lists  access  control  lists  (acls)  of  one  or  more  files  in  symbolic,  "short"  form,  one  file's  ACL  per  line 
of  output,  followed  by  the  file  name;  see  acl  (5)  for  ACL  syntax. 

Options 

lsacl  recognizes  the  following  option: 

-1     Print  acls  in  long  form.  Each  file's  ACL  can  be  more  than  one  line  long,  and  is  always  preceded 
by  file  name,  colon,  andnewline.  Consecutive  file  names  are  separated  by  blank  lines. 

If  a  hyphen  (-)  is  given  as  a  file  name  argument,  lsacl  prints  the  ACL  for  the  standard  input.  By 
default,  it  prints  the  file  name  as  -.  For  the  -1  option  it  prints  a  file  name  of  <stdin>. 

Unlike  Is,  lsacl  cannot  list  acls  of  files  in  subdirectories  automatically  or  list  the  ACL  entries  of  the 
files  in  the  current  directory  by  default.  A  good  way  to  do  the  latter  is: 

lsacl  * 

or 

lsacl   .*  * 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed. 

If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 
If  any  internationalization  variable  contains  an  invalid  setting,  lsacl  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

RETURN  VALUE 

If  lsacl  succeeds,  it  returns  zero.  If  invoked  incorrectly,  it  returns  a  value  of  1.  If  lsacl  is  unable  to 
read  the  ACL  for  a  specified  file,  it  prints  an  error  message  to  standard  error,  continues,  and  later  returns  a 
value  of  2. 

EXAMPLES 

List  the  ACL  for  the  file  dir/filel : 

lsacl  dir/filel 

List  acls  for  all  files  in  the  current  directory,  in  long  form. 

lsacl  -1   .*  * 
List  ACLs  for  all  files  under  mydir: 

find  mydir  -print    |   sort    |   xargs  lsacl 

DEPENDENCIES 

lsacl  will  fail  when  the  target  file  resides  on  a  file  system  which  does  not  support  ACLs. 
NFS: 

lsacl  is  not  supported  on  remote  files. 

AUTHOR 

lsacl  was  developed  by  HP. 

SEE  ALSO 

chacl(l),  getaccess(l),  ls(l),  getacl(2),  acl(5). 
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NAME 

m4  -  macro  processor 

SYNOPSIS 

m4  [options]  [file  ...] 

DESCRIPTION 

m4  is  a  macro  processor  intended  as  a  front  end  for  Ratfor,  C,  and  other  languages.  Each  of  the  argument 
files  is  processed  in  order;  if  there  are  no  files,  or  if  a  file  name  is  -,  standard  input  is  read.  The  processed 
text  is  written  to  standard  output. 

Options 

m4  recognizes  the  following  options: 

-e  Operate  interactively.  Interrupts  are  ignored  and  the  output  is  unbuffered.  Using  this 

mode  may  be  very  difficult. 

-s  Enablelinesync  output  for  the  C  preprocessor  (#1  ine ...) 

-Bint      Change  the  size  of  the  push-back  and  argument  collection  buffers  from  the  default  of  4,096. 

-Hint      Change  the  size  of  the  symbol  table  hash  array  from  the  default  of  199.  The  size  should  be 
prime. 

-Sint      Change  the  size  of  the  call  stack  from  the  default  of  100  slots.  Macros  take  three  slots,  and 
non macro  arguments  take  one. 

-Tint      Change  the  size  of  the  token  buffer  from  the  default  of  512  bytes. 

To  be  effective,  the  options  listed  above  must  appear  before  any  file  names  and  before  any  -D  or  -U 
options. 

-Dname[=val  ] 

Define  name  as  val  or  as  null  ifval  isomitted. 

-Uname  Undefine name. 

Macro  Calls 

Macro  calls  have  the  form: 

name(argl,  arg2,    ...  ,argn) 

The  left  parenthesis  ( ()  must  immediately  follow  the  name  of  the  macro.  If  the  name  of  a  defined  macro  is 
not  followed  by  a  (,  it  is  deemed  to  be  a  call  of  that  macro  with  no  arguments.  Potential  macro  names  con- 
sist of  alphabetic  letters,  digits,  and  underscore  (_);  the  first  character  cannot  be  a  digit. 

Leading  unquoted  blanks,  tabs,  and  newlines  are  ignored  while  collecting  arguments.  Left  and  right  single 
quotes  ( '  and  ' )  are  used  to  quote  strings.  The  value  of  a  quoted  string  is  the  string  stripped  of  the  quotes. 

When  a  macro  name  is  recognized,  its  arguments  are  collected  by  searching  for  a  matching  right 
parenthesis.  If  fewer  arguments  are  supplied  than  are  in  the  macro  definition,  the  trailing  arguments  are 
taken  to  be  null.  Macro  evaluation  proceeds  normally  during  the  collection  of  the  arguments,  and  any  com- 
mas or  right  parentheses  which  happen  to  turn  up  within  the  value  of  a  nested  call  are  as  effective  as  those 
in  the  original  input  text.  After  argument  collection,  the  value  of  the  macro  is  pushed  back  onto  the  input 
stream  and  rescanned. 

Built-in  Macro  Names 

m4  makes  avai  I  ablethe  foil  owing  built-in  macros.  They  can  be  redefined,  but,  once  this  is  done,  the  original 
meaning  is  lost.  Their  values  are  null  unless  otherwise  stated. 

changecom  Change  left  and  right  comment  markers  from  the  default  #  and  newline.  With  no  argu- 
ments, the  comment  mechanism  is  effectively  disabled.  With  one  argument,  the  left 
marker  becomes  the  argument  and  the  right  marker  becomes  newline.  With  two  argu- 
ments, both  markers  are  affected.  Comment  markers  may  be  up  to  five  characters  long. 

changequote  Change  quote  symbols  to  the  first  and  second  arguments.  The  symbols  may  be  up  to 
five  characters  long,  changequote  without  arguments  restores  the  original  values 
(i.e.,  1  and  ' ). 
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deer  Returns  the  value  of  its  argument  decremented  by  1. 

define  Thesecond  argument  is  installed  as  the  valueof  the  macro  whose  nameisthe  first  argu- 

ment. Each  occurrence  of  $n  in  the  replacement  text,  where  n  is  a  digit,  is  replaced  by 
the  nth  argument.  Argument  0  is  the  name  of  the  macro;  missing  arguments  are 
replaced  by  the  null  string;  $#  is  replaced  by  the  number  of  arguments;  $*  is  replaced 
by  a  list  of  all  the  arguments  separated  by  commas;  $@  is  equivalent  to  $*,  but  each 
argument  is  quoted  (with  the  current  quotes). 

defn  Returns  the  quoted  definition  of  its  arguments.  It  is  useful  for  renaming  macros,  espe- 

cially built-ins. 

divert  m4  maintains  10  output  streams,  numbered  0  to  9.  Thefinal  output  is  the  concatenation 

of  the  streams  in  numerical  order;  initially,  stream  0  is  the  current  stream.  The 
divert  macro  changes  the  current  output  stream  to  its  (digit-string)  argument.  Out- 
put diverted  to  a  stream  other  than  0  through  9  is  discarded. 

divnum  Returns  the  val  ue  of  the  current  output  stream. 

dnl  Reads  and  discards  characters  up  to  and  including  the  next  newline. 

dumpdef  Prints  current  names  and  definitions,  for  the  named  items,  or  for  all  if  no  arguments  are 

given. 

errprint  Prints  its  argument  on  the  diagnostic  output  file. 

eval  Evaluates  its  argument  as  an  arithmetic  expression,  using  32-bit  arithmetic.  Operators 

include +,  -,  *,  /,  %,  **  (exponentiation),  bitwise  &,  |,  ",  and  ~,  relational,  and 
parentheses.  Octal  and  hexadecimal  numbers  may  be  specified  as  in  C.  The  second 
argument  specifies  the  radix  for  the  result;  the  default  is  10.  The  third  argument  may 
be  used  to  specify  the  minimum  number  of  digits  in  the  result. 

hpux  Is  a  predefined  object  with  a  null  value. 

ifdef  If  the  first  argument  is  defined,  the  value  is  the  second  argument;  otherwise  the  third. 

If  there  is  no  third  argument,  the  value  is  null.  The  word  unix  is  predefined  on  HP-UX 
system  versions  of  m4 . 

ifelse  Has  three  or  more  arguments.  If  the  first  argument  is  the  same  string  as  the  second, 

then  the  value  is  the  third  argument.  If  not,  and  if  there  are  more  than  four  arguments, 
the  process  is  repeated  with  arguments  4,  5,  6  and  7.  Otherwise,  the  value  is  either  the 
fourth  string,  or,  if  it  is  not  present,  null. 

include  Returns  the  contents  of  the  file  named  in  the  argument. 

incr  Returns  the  value  of  its  argument  incremented  by  1.  The  value  of  the  argument  is  cal- 

culated by  interpreting  an  initial  digit-string  as  a  decimal  number. 

index  Returns  the  position  in  its  first  argument  where  the  second  argument  begins  (zero  ori- 

gin), or  -1  if  thesecond  argument  does  not  occur. 

len  Returns  the  number  of  characters  in  its  argument. 

m4exit  Causes  immediate  exit  from  m4.  Argument  1,  if  given,  is  the  exit  code;  the  default  is  0. 

m4wrap  Argument  1  is  pushed  back  at  final  EOF;  for  example:  m4wrap  (  'cleanup  ( )  '  ) 

maketemp  Fills  in  a  string  of  XXXXX  in  its  argument  with  the  current  process  I D. 

popdef  Removes  current  definition  of  its  arguments,  exposing  the  previous  one,  if  any. 

pushdef  Similar  to  define,  but  saves  any  previous  definition. 

shift  Returns  all  but  its  first  argument.  The  other  arguments  are  quoted  and  pushed  back 

with  commas  in  between.  The  quoting  nullifies  the  effect  of  the  extra  scan  that  will  sub- 
sequently be  performed. 

sinclude  Identical  to  include,  except  that  it  says  nothing  if  the  file  is  inaccessible. 

substr  Returns  a  substring  of  its  first  argument.  The  second  argument  is  a  zero-origin  number 

selecting  the  first  character;  the  third  argument  indicates  the  length  of  the  substring.  A 
missing  third  argument  is  taken  to  be  large  enough  to  extend  to  the  end  of  the  first 
string. 
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syscmd 


Executes  the  HP-UX  system  command  given  in  the  first  argument.  No  value  is 
returned. 


sysval 
traceof f 


Is  the  return  code  from  the  last  call  to  syscmd. 


Turns  off  trace  globally  and  for  any  macros  specified.  Macros  specifically  traced  by 
traceon  can  be  untraced  only  by  specific  calls  to  traceof  f. 


traceon 


With  no  arguments,  turns  on  tracing  for  all  macros  (including  built-ins).  Otherwise, 
turns  on  tracing  for  named  macros. 


translit 


Transliterates  the  characters  in  its  first  argument  from  the  set  given  by  the  second 
argument  to  the  set  given  by  the  third.  No  abbreviations  are  permitted. 


undef ine 


Removes  the  definition  of  the  macro  named  in  its  argument. 


undivert 


Causes  immediate  output  of  text  from  diversions  named  as  arguments,  or  all  diversions 
if  no  argument.  Text  may  be  undiverted  into  another  diversion.  Undiverting  discards 
the  diverted  text. 


(XPG4  only.)  It  is  an  error  to  specify  an  argument  containing  any  non-numeric  character  for  the  built-in- 
macros:  deer,  divert,  incr,  m4exit,  substr,  undivert , and  eval. 

SEE  ALSO 

cpp(l),  ratfor(l). 

STANDARDS  CONFORMANCE 

m4:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4 
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NAME 

hp9000s200,  hp9000s300,  hp9000s500,  hp9000s800,  pdpll,  u3b,  u3b2,  u3b5,  u3blO,  u370,  vax  -  provide 
truth  value  about  processor  type 

SYNOPSIS 

hp9000s200 

hp9000s300 

hp9000s400 

hp9000s500 

hp9000s700 

hp9000s800 

hp-mc680x0 

hp-pa 

pdpll 

u3b 

u3b2 

u3b5 

u3bl0 

u370 

vax 

DESCRIPTION 

The  following  commands  return  a  true  value  (exit  code  0)  if  the  a  processor  type  matches  the  command 
name.  Otherwise  a  false  value  (exit  code  non-zero)  is  returned.  These  commands  are  commonly  used 
within  make  makefiles  and  shell  procedures  toimprove  portability  of  applications  (see  make(l)). 


Command 

True  for: 

Command 

True  for: 

hp9000s200 

Series  200 

pdpll 

PDP-11/45  or  PDP-11/70 

hp9000s300 

Series  300 

u3b 

3B20  computer 

hp9000s400 

Series  400 

u3b2 

3B2  computer 

hp9000s500 

Series  500 

u3b5 

3B5  computer 

hp9000s700 

Series  700 

u3bl0 

3B 10  computer 

hp9000s800 

Series  800/700 

u370 

IBM  System/370  computer 

hp-mc680x0 

Series  200,  300,  or  400 

vax 

VAX-11/750  or  VAX-11/780 

hp-pa 

Series  700  or  800 

EXAMPLES 

Given  a  shell  script  that  must  behave  differently  when  run  on  an  HP  9000  Series  700  or  800  system,  select 
the  correct  code  segment  to  be  executed: 

if  hp9000s800 
then 

#  system  is  Series  700  or  800. 
if  hp9000s700 
then 

#  System  is  Series  700 

Series  700  code  fragment  goes  here 

else 

#  System  is  Series  800 

Series  800  code  fragment  goes  here 

fi 

fi 

WARNINGS 

hp9000s800  always  returns  true  on  both  Series  800  and  Series  700  systems.  Therefore,  when  using  this 
command  in  scripts  to  determine  hardware  type,  always  use  both  hp9000s800  and  hp9000s700  in 
the  appropriate  sequence  to  ensure  correct  results  (see  exam  ples). 

machid(l)  will  no  longer  provide  support  for  future  machines  beyond  the  Series  800  and  Series  700  sys- 
tems. Decisions  should  be  based  on  the  hardware  and  software  configuration  information  returned  by 
getconf(l). 


Section  1-488 


-1- 


HP-UX  Release  Hi:  December  2000 


machid(l)  machid(l) 


SEE  ALSO 

getconf(l),  make(l),  sh(l),  test(l),  true(l). 
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NAME 

mai  I ,  rmai  I  -  send  mai  I  to  users  or  read  mai  I 

SYNOPSIS 

mail  [+]  [-epqr]  [-f  file] 

mail  [-dt]  person  ... 
rmail  [-dt]  person  ... 

Remarks: 

See  mailx(l)  and  elm(l)  for  an  enhanced  user  mail  interface. 
DESCRIPTION 

The  mail  command,  when  used  without  arguments,  prints  the  user's  mail,  message-by-message,  in  last- 
in,  first-out  order. 

For  each  message,  mail  prints  a  ?  prompt  and  reads  a  line  from  the  standard  input  to  determine  the 
disposition  of  the  message.  Commands  that  automatically  proceed  to  the  next  message  exit  from  mail  if 
mail  already  on  the  last  message. 

Commands 

mail  supports  the  foil  owing  commands: 

<new-line>      Go  on  to  next  message.  Exit  if  already  on  last  message. 

+  Same  as  <new-line>. 

n  Same  as  <new-line>. 

d  Delete  message  and  go  on  to  next  message. 

p  Print  message  again. 

Go  back  to  previous  message. 

s  [files]         Save  message  in  the  named  files  (default  is  mbox),  mark  the  message  for  deletion 
from  the  user's  mailfile,  and  proceed  to  next  message. 

y  [files]         Sameass  [files]. 

w  [files]         Save  message  without  its  header  (the  "From  ..."  line),  in  the  named  files  (default  is 
mbox),  mark  the  message  for  deletion,  and  go  on  to  next  message. 

m  person  ...  Mail  the  message  to  each  named  person,  mark  the  message  for  deletion,  and  go  on  to 
next  message. 

q  Put  undeleted  mail  back  in  the  mailfile  and  stop. 

eot  (Ctrl-D)  Same  as  q. 

x  Abort.  Leave  original  mailfile  unchanged  and  stop. 

!  command  Escape  to  the  command  interpreter  and  execute  command. 

?  Print  a  command  summary. 

*  Same  as?. 

Command-Line  Options 

The  foil  owing  command-line  options  alter  printing  of  the  mail: 

+  Cause  messages  to  be  printed  in  first-in,  first-out  order, 

-e  Suppresses  printing  of  mail  and  returns  the  exit  value: 

0  =  Mail  present 

1  =No  mail 

2  =  Other  error 

-p  Prints  all  mail  without  prompting  for  disposition. 

-q  Causes  mail  to  terminate  if  an  interrupt  is  received.  Normally  an  interrupt  only 

causes  the  termination  of  the  printing  of  the  current  message. 
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-r  Same  as +. 

-f  file  Causes  mail  to  use fi I e  (for  example,  mbox)  instead  of  the  default  mailfile. 

-t  Causes  the  outbound  message  to  be  preceded  by  each  person  the  mail  is  sent  to.  A 

person  is  usually  a  user  name  recognized  by  login  (see  login (1)).  If  a  person  being 
sent  mail  is  not  recognized,  or  if  mail  is  interrupted  during  input,  the  file 
dead. letter  will  be  saved  to  allow  editing  and  resending.  Note  that 
dead. letter  is  regarded  as  a  temporary  file  in  that  it  is  recreated  every  time 
needed,  erasing  the  previous  contents  of  dead,  letter . 

-d  Causes  mail  to  deliver  mail  directly.  This  isolates  mail  from  making  routing  deci- 

sions, and  allows  it  to  be  used  as  a  local  delivery  agent.  Typically  this  option  is  used 
by  auto-routing  facilities  when  they  deliver  mail  locally. 

When  persons  are  named,  mail  takes  the  standard  input  up  to  an  end-of-file  (or  up  to  a  line  consisting  of 
just  a  . )  and  adds  it  to  each  person's  mailfile.  The  message  is  preceded  by  the  sender's  name  and  a  post- 
mark. 

To  denote  a  recipient  on  a  remote  system,  prefix  person  by  the  system  name  and  exclamation  mark  (see 
uucp(l)).  Everything  after  the  first  exclamation  mark  in  person  is  interpreted  by  the  remote  system.  In 
particular,  if  person  contains  additional  exclamation  marks,  it  can  denote  a  sequence  of  machines  through 
which  the  message  is  to  be  sent  on  the  way  to  its  ultimate  destination.  For  example,  specifying  alb!  cde 
as  a  recipient's  name  causes  the  message  to  be  sent  to  user  b!  cde  on  system  a.  System  a  then  inter- 
prets that  destination  as  a  request  to  send  the  message  to  user  cde  on  system  b.  This  might  be  useful,  for 
instance,  if  the  sending  system  can  access  system  a  but  not  system  b.  mail  does  not  use  uucp  if  the 
remote  system  is  the  local  system  name  (i  .e.,  localsystemluser). 

The  mailfile  can  be  manipulated  in  two  ways  to  alter  the  function  of  mail.  The  other  permissions  of 
the  file  can  be  read-write,  read-only,  or  neither  read  nor  write  to  allow  different  levels  of  privacy.  If 
changed  to  other  than  the  default,  the  file  is  preserved,  even  when  empty,  to  perpetuate  the  desired  per- 
missions. Thefilecan  also  contain  the  first  line: 

Forward  to  person 

which  causes  all  mail  sent  to  the  owner  of  the  mailfile  to  be  forwarded  to  person.  This  is  especially 
useful  for  forwarding  all  of  a  person's  mail  to  a  given  machine  in  a  multiple-machine  environment.  I  n  order 
for  forwarding  to  work  properly  the  mailfile  should  have  "mail"  as  group  id,  and  the  group  permission 
should  be  read-write. 

rmail  only  permits  the  sending  of  mail,    uucp  uses  rmail  as  a  security  precaution. 

When  a  user  logs  in,  the  command  mail  -e  can  be  used  to  detect  the  presence  of  mail,  if  any,  and  so 
indicate.  When  terminating,  mail  produces  a  notification  message  if  new  mail  arrived  while  mail  was 
running. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_TIME  determines  the  format  and  contents  of  the  displayed  date  and  time  strings. 

If  LC_TIME  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANGisusedas 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  mail  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  envi  ron (5). 

When  set,  the  TMPDIR  environment  variable  specifies  a  directory  to  be  used  for  temporary  files,  overrid- 
ing the  default  directory  /tmp. 

I  nternational  Code  Set  Support 

Between  hp-ux  systems,  single-  and  multi-byte  character  code  sets  are  supported  within  mail  text. 
Headers  are  restricted  to  characters  from  the  7-bit  usascii  code  set  (see  ascii  (5)). 

WARNINGS 

Conditions  sometimes  result  in  a  failureto  remove  a  lock  file. 

After  an  interrupt,  the  next  message  may  not  be  printed.  To  force  printing,  type  a  p. 

Lines  that  look  like  postmarks  in  the  message  (that  is,  "From  ...")  are  preceded  by  >. 
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mail  treats  a  line  consisting  solely  of  a  dot  ( .  )  as  the  end  of  the  message,  except  when  the  rmail  -d 
command  is  used. 

The  maximum  allowable  line  length  in  mail  messages  is  BUFSIZ  bytes  as  defined  in 
/usr/include/stdio . h.  If  line  length  exceeds  this  limit,  mail  truncates  the  line  starting  at 
beginning-of-line,  and  uses  only  thetrailing  BUFSIZ  characters. 

Using  two  separate  mail  programs  to  access  the  same  mail  file  simultaneously  (usually  inadvertently  from 
two  separate  windows)  can  cause  unpredictable  results. 

Some  sites  that  have  programs  that  adhere  strictly  to  RFC-822  will  fail  to  deliver  a  message  if  any  of  the 
recipient  fields  below  is  missing. 


To: 

resent-to : 
cc : 

resent-cc : 
bcc : 

resent -bcc : 

You  can  add  the  RFC-822  commands  into  the  mail  program  buffer/editor.  For  instance: 

mail  userl@domain.com 
From:  user2@domain.com 
Subject :   This  is  a  test 
To:  test_address@domain.com 

This  is  a  test 


FILES 

/var/mail/* . lock 
dead. letter 
/tmp/ma* 
$MAIL 

$HOME/mbox 
/etc/passwd 
/var/mail 
/var/mail/  user 


Lock  for  mail  directory 
Unmailabletext 
Temporary  file 

Variable  containing  path  name  of  mailfile 
Saved  mail 

To  identify  sender  and  locate  persons 

Directory  for  incoming  mail  (mode  775,  group  id  mail) 

I  ncoming  mail  for  user;  that  is,  the  mailfile  (mode  660,  group  id  mail) 


SEE  ALSO 

login(l),  mailx(l),  uucp(l),  write(l). 

STANDARDS  CONFORMANCE 

mail:  SVID2,  SVID3,  XPG2,  XPG3 

rmail:  SVID2,  SVID3 
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NAME 

mailfrom  -  summarize  mail  folders  by  subject  and  sender 
SYNOPSIS 

mailfrom  [-hnQqStv]  [-s  status]  [folder  |  username]... 
DESCRIPTION 

The  mailfrom  command  reads  one  or  more  mail  folders  and  outputs  one  line  per  message  in  the  form: 
from  [subject] 

where  from  is  the  name  of  the  person  the  message  is  from,  and  subject  is  the  subject  of  the  message,  if 
present.  If  mailfrom  determines  that  the  message  is  from  you,  the  from  portion  will  read  To  user, 
where  user  is  the  user  the  message  was  sent  to.  This  happens  when  you  receive  a  copy  of  a  letter  you  sent. 

The  default  folder  is  your  incoming  mailbox,  /var/mail/yourloginname.  See  the  Operands  subsection 
below. 

Options 

mailfrom  recognizes  the  following  options: 

-h  Print  a  brief  help  message  summarizing  the  options. 

-n  Number  the  messages  using  the  same  numbering  scheme  used  by  readmail . 

-Q  Very  quiet  mode.  Only  error  messages  are  produced.  This  option  is  useful  in  shell 

scripts,  where  only  the  success  or  failure  of  the  program  is  important,  and  output  is 
not  desired. 

-q  Quiet  mode.  Output  only  a  one-linesummary  for  each  mailbox  or  folder. 

-S  Add  a  summary  of  the  number  of  messages  by  message  status  in  each  mailbox  or 

folder.  To  get  the  summary  only,  use  this  with  the  -q  option.  The  summary  has  the 
form: 

Folder  contains : 
New  messages :  n 
Unread  messages :  u 
Read  messages:  r 

If  an  item  count,  n,  r,  or  u  is  zero,  the  line  is  omitted. 

-s  status  Only  display  headers  from  messages  with  the  given  status,  status  can  be  one  of  new, 
old,  read,  or  unread,  old  and  unread  are  equivalent.  The  -s  option  can  be 
repeated  to  print  header  information  from  more  than  one  category,  for  example,  only 
new  and  unread  messages.  The  values  can  be  abbreviated  to  their  first  letters.  The 
default  is  all  messages. 

-t  Tidy  mode.  If  the  from  field  is  long  enough  to  displace  the  subject  field  from  its  normal 

start  column,  move  the  subject  down  onto  the  next  line. 

-v  Verbose  mode.  Print  a  descriptive  header  before  listing  the  contents  of  each  mailbox 

or  folder. 


Operands 

mailfrom  recognizes  the  following  optional  operands: 
folder  |  username 

A  file  name  or  the  name  of  a  mail  user  on  your  system.  You  can  use  the  =filename 
format  to  specify  a  folder  in  your  mail  directory,  defined  bythemaildir  string  vari- 
ablein  your  elmrc  configuration  file. 

mailfrom  searches  for  the  value  as  a  file  name  relative  to  your  current  directory. 
Then,  if  the  file  name  is  not  an  absolute  path,  it  searches  for  the  value  relative  to  the 
incoming  mailbox  directory,  /var/mail.  The  first  file  found  is  selected.  You  must 
have  read  access  to  the  file. 


EXIT  STATUS 

mailfrom  returns  the  following  values: 
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0  Messages  matching  status  are  present. 

1  No  messages  matching  status  are  present,  but  there  are  some  messages. 

2  There  are  no  messages  at  all. 

3  An  error  occurred. 

If  multiple  mailboxes  or  folders  are  specified,  the  exit  status  only  applies  to  the  last  one  examined.  This 
can  be  used  in  scripts  to  determine  what  kind  of  mail  a  user  has. 

EXAMPLES 

Display  header  information  from  all  the  messages  in  your  mailbox, 
mailf rom 

Display  header  information  from  all  new  messages  in  your  mailbox, 
mailfrom  -s  new 

Assumingyou  have  the  proper  file  permissions  to  read  guest's  mail,  printout  header  information  from  all 
new  and  unread  messages  in  guest's  incoming  mailbox. 

mailfrom  -s  new  -s  unread  guest 

Print  only  a  summary  of  how  many  new,  unread,  and  read  messages  are  in  your  incoming  mailbox, 
mailfrom  -q  -S 

FILES 

$HOME/  .  elm/elmrc    Your  elm  configuration  file, 
/var/mail  Directory  of  incoming  mailboxes. 

AUTHOR 

mailfrom  was  developed  by  HP. 

SEE  ALSO 

elm(l),  mail(l),  mailx(l),  readmail(l). 
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NAME 

mailq  -  prints  the  mail  queue 

SYNOPSIS 

mailq  [-v] 

DESCRIPTION 

mailq  prints  a  summary  of  the  mail  messages  queued  for  future  delivery. 

Thefirst  line  printed  for  each  message  shows  the  internal  identifier  used  on  this  host  for  the  message,  the 
size  of  the  messagein  bytes,  the  date  and  time  the  message  was  accepted  into  the  queue,  and  the  envelope 
sender  of  the  message.  The  second  line  shows  the  error  message  that  caused  this  message  to  be  retained  in 
the  queue;  it  will  not  be  present  if  the  message  is  being  processed  for  the  first  time.  The  following  lines 
show  message  recipients,  one  per  line. 

mailq  is  identical  to  sendmail  -bp. 

The  options  are  as  follows: 

Options 

-v  Print  verbose  information.  This  adds  the  priority  of  the  message  and  a  single  character  indicator 
("+"  or  blank)  indicating  whether  a  warning  message  has  been  sent  on  thefirst  line  of  the  message. 
Additionally,  extra  lines  may  be  intermixed  with  the  recipients  indicating  the  "controlling  user" 
information;  this  shows  who  will  own  any  programs  that  are  executed  on  behalf  of  this  message 
and  the  name  of  the  alias  this  command  expanded  from,  if  any. 

RETURN  VALUE 

Themailq  utility  exits  0  on  success,  and  >0  if  an  error  occurs. 

AUTHOR 

mailq  was  developed  by  the  University  of  California,  Berkeley,  and  originally  appeared  in  4.0BSD. 
FILES 

/var/spool/mqueue/*      mail  queue  files 

SEE  ALSO 

sendmail(lM). 
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NAME 

mailstats-  print  mail  traffic  statistics 

SYNOPSIS 

mailstats  [-o]  [-C  cffile]  [-f  stfile] 

DESCRIPTION 

mailstats  reads  and  interprets  the  sendmail  statistics  file,  /etc/mail/sendmail .  st,  then 
prints  out  the  mail  traffic  statistics.  If  /etc/mail/sendmail .  st  exists,  sendmail  collects  statis- 
tics about  your  mail  traffic  and  stores  them  in  the  statistics  file.  This  file  does  not  grow. 

Statistics  are  gathered  on  a  per-mailer  basis  for  each  mailer  defined  in  the  sendmail  configuration  file. 
Statistics  are  kept  on  the  number  of  messages  and  the  number  of  bytes  for  all  inbound  and  outbound  traffic. 

The  mailstats  utility  displays  the  time  at  which  statistics  collection  was  started  on  the  first  line.  Then, 
the  statistics  of  each  mailer  is  displayed  on  a  single  line,  each  with  the  following  white  space  separated 
fields  (seethe  "EXAMPLES"  section  below): 

M  The  mailer  number. 

msgsf  r  Number  of  messages  from  the  mailer. 

bytes_from  Kbytes  from  the  mailer. 

msgsto  Number  of  messages  to  the  mailer. 

bytes_to  Kbytes  to  the  mailer. 

msgsrej  Number  of  messages  rejected. 

msgsdis  Number  of  messages  discarded. 

Mailer  The  name  of  the  mailer. 

After  this  display,  a  line  totaling  the  values  for  all  of  the  mailers  is  displayed,  separated  from  the  previous 
information  by  a  line  containing  only  equals("=")  characters. 

Options 

The  options  are  as  follows: 

-C    Read  the  specified  file  instead  of  the  default  /etc/mail/sendmail .  cf  file. 

-f    Read    the    specified    statistics    file    instead    of    the    statistics    file    specified    in  the 
/ etc/mail/ sendmail .  cf  file. 

-o    Do  not  display  the  name  of  the  mailer  in  the  output. 

To  clear  the  statistics  file,  execute,  as  root: 

cp/dev/null/etc/mail/sendmail .  st 

RETURN  VALUE 

Themailstats  utility  exits  0  on  success,  and  >0  if  an  error  occurs. 

DIAGNOSTICS 

mailstats  generates  error  messages  if  the  statistics  file  is  not  accessible  or  if  the  size  of  the  statistics  file 
has  changed.  E  rror  messages  are: 

mailstats:    file  size  changed 

Either  /etc/mail/sendmail .  st  is  zero  length,  meaning  that  no  mail  has  been  transferred 
since  it  was  cleared  out,  or  its  size  has  changed.  Since  the  size  of  this  file  is  supposed  to  remain 
constant,  any  change  in  size  means  that  the  file  is  invalid. 

mailstats:    /etc/mail/sendmail . st :  No  such  file  or  directory 

Thestatisticsfiledoes  not  exist. 

mailstats:    /etc/mail/sendmail . st :   Permission  denied 

The  statistics  file's  permissions  are  set  so  that  you  cannot  read  it. 

EXAMPLES 

Here  is  a  typical  example  of  mailstats  output: 
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Statistics  from  Thu  Jul  11  14:12:40  1996 

M      msgsfr  bytes_from       msgsto         bytes_to  msgsrej  msgsdis  Mailer 

0                 0  OK                3                    4K  0               0  prog 

3                3  4K                0                    OK  0               0  local 

5                2  IK              11                   UK  4               0  esmtp 


T  13  13K  14  15K  4  0 

This  example  shows  that  mailers  0,  3  and  5  have  handled  the  given  amounts  of  mail  traffic  si  nee  Thursday, 
J  ul  11th,  Specifically,  sendmail  has  sent  11  messages  containing  11  kilobytes  via  mailer  esmtp  (M  5), 
but  has  4  messages  rejected  via  mailer  esmtp  (M  5). 


AUTHOR 

mailstats  was  developed  by  the  University  of  California,  Berkeley. 
FILES 

/etc/mail/sendmail .  st        mail  traffic  statistics  file 
/etc/mail/sendmail .  cf        sendmail  configuration  file 


SEE  ALSO 

sendmail(livi). 
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NAME 

mailx  -  interactive  message  processing  system 


SYNOPSIS 
Send  mode: 

mailx  [-FUm]  [-s  subject]  [-r  address]  [-h  number]  address  ... 


Receive  mode: 

mailx  -e 

mailx  [-UHLiNn]  [-u  user] 
mailx  -f  [-UHLiNn]  [filename] 


Obsolescent: 

mailx  [-f  filename]  [-UHLiNn] 


DESCRIPTION 

mailx  provides  a  comfortable,  flexible  environment  for  sending  and  receiving  messages  electronically. 
When  reading  mail,  mailx  provides  commands  to  facilitate  saving,  deleting,  and  responding  to  messages. 
When  sending  mail,  mailx  allows  editing,  reviewing  and  other  modification  of  the  message  as  it  is 
created. 

Incoming  mail  for  each  user  is  stored  in  a  standard  file  called  the  system  mailbox  for  that  user.  When 
using  mailx  to  read  messages,  the  system  mailbox  is  used  unless  an  alternate  mailbox  file  is  specified  by 
using  the  -f  option  with  or  without  a  specific  filename.  As  incoming  messages  are  read  from  the  system 
mailbox,  they  are  marked  to  be  moved  to  a  secondary  file  for  storage  (unless  specific  action  is  taken)  so  that 
the  messages  need  not  be  seen  again.  This  secondary  file  is  called  the  mbox  and  is  usually  located  in  the 
user's  HOME  directory  (see  MBOX  description  under  environment  variables  below  for  a  description  of 
this  file  and  other  environment  variables  used  by  mailx).  Messages  remain  in  this  file  until  specifically 
removed. 

Command-line  options  start  with  a  hyphen  (-),  and  any  other  arguments  are  assumed  to  be  destinations 
(recipients).  If  no  recipients  are  specified,  mailx  attempts  to  read  messages  from  the  system  mailbox. 

Recipient  addresses  specified  on  the  command  line  must  total  less  than  1024  characters  in  length.  You  may 
declare  an  alias  or  group  (see  COM  man  ds  below)  to  specify  a  recipient  address  or  list  of  addresses  of  up 
to  8191  characters,  and  use  that  alias  or  group  name  (though  each  address  in  the  list  must  still  be  less  than 
1024  characters).  If  you  wish  to  specify  a  list  of  recipient  addresses  of  greater  length  than  this,  have  your 
system  administrator  declare  an  alias  or  group  in  the  system  alias  file  /etc/mail/aliases  and  use 
that  alias  name  instead. 


Options 

mailx  recognizes  the  following  command-line  options: 

-e  Test  for  presence  of  mail,    mailx  prints  nothing  and  exits  with  a  successful  return 

code  if  there  is  mail  to  read.  Sometimes  used  in  login  scripts  such  as 
$HOME/  .profile  to  check  for  mail  during  login. 

-f  Read  messages  from  filename  instead  of  the  user's  system  mailbox.  If  filename  is  not 

specified,  the  secondary  mbox  is  used. 

-F  Record  the  message  in  a  file  named  after  the  first  recipient.  Overrides  the  record 

environment  variable,  if  set. 

-h  number     The  number  of  network  "hops"  made  so  far.  This  is  provided  for  network  software  to 
prevent  infinite  deli  very  loops. 

-H  Print  header  summary  only. 

-L  Print  complete  header  information  only. 

-i  Ignore  interrupts.  Also  see  the  description  of  the  ignore  environment  below, 

-n  Do  not  initializefrom  the  system  default  mailx.  rc  file. 

-m  Do  not  add  MIME  header  lines  Mime  Version,  Content  Type  &  Content  Encoding  to 

the  header  information  whilesending  mails. 
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— N  Do  not  print  initial  header  summary. 

-r  address     Pass  address  to  network  delivery  software.  All  tilde  commands  are  disabled, 
-s  subject      Set  the  Subject  header  field  to  subject. 

-u  user  Read  user's  mailbox.  Can  be  used  only  if  read  access  to  user's  mailbox  is  not  read  pro- 

tected. 

-U  Convert  UUCP-style  addresses  to  I nternet  standards.  Overrides  the  conv  environ- 

ment variable. 

-d  Turn  on  debugging  output.  Neither  particularly  interesting  nor  recommended. 

When  reading  mail,  mailx  operates  in  command  mode.  A  header  summary  of  the  first  several  mes- 
sages is  displayed,  followed  by  a  prompt  indicating  that  mailx  can  accept  regular  commands  (see  com- 
mands below).  When  sending  mail,  mailx  operates  in  input  mode.  If  no  subject  is  specified  on  the 
command  line,  a  prompt  for  the  subject  is  printed.  As  the  message  is  typed,  mailx  reads  the  message 
and  stores  it  in  a  temporary  file.  Commands  can  be  entered  by  beginning  a  line  with  the  tilde  (")  escape 
character  followed  by  a  singlecommand  letter  and  optional  arguments.  SeeTi lde  escapes  for  a  summary 
of  these  commands. 

The  behavior  of  mailx  at  any  given  time  is  governed  by  a  set  of  environment  variables;  flags  and 
valued  parameters  that  are  set  and  cleared  by  using  the  set  and  unset  commands.  See  environment 
variables  below  for  a  summary  of  these  parameters. 

Recipients  listed  on  the  command  line  can  be  of  three  types:  login  names,  shell  commands,  or  alias  groups. 
Login  names  can  be  any  network  address,  including  mixed  network  addressing.  If  the  recipient  name 
begins  with  a  pipe  symbol  ( | ),  the  rest  of  the  name  is  assumed  to  be  a  shell  command  to  pipe  the  message 
through.  This  provides  an  automatic  interface  with  any  program  that  reads  the  standard  input,  such  as 
lp  (see  lp(D)  for  recording  outgoing  mail  on  paper.  Alias  groups  are  set  by  the  alias  command  (see  com- 
mands below)  and  are  lists  of  recipients  of  any  type. 

Regular  commands  are  of  the  form 

[command]  [msglist  ]  [  arguments  ] 

If  no  command  is  specified  in  command  mode,  print  is  assumed.  In  input  mode,  commands  are  recognized 
by  the  escape  character  (tilde  unless  redefined  by  the  escape  environment  variable),  and  lines  not 
treated  as  commands  are  treated  as  i  nput  for  the  message. 

Each  message  is  assigned  a  sequential  number,  and  there  is  always  the  notion  of  a  current  message, 
marked  by  a  >  in  the  header  summary.  Many  commands  take  an  optional  list  of  messages  (msglist)  to 
operate  on,  which  defaults  to  the  current  message.  A  msglist  is  a  list  of  message  specifications  separated 
by  spaces.  The  message  list  can  include: 

n  Message  number  n. 

The  current  message. 

A  The  first  undeleted  message. 

$  The  last  message. 

*  All  messages. 

n-m       An  inclusive  range  of  message  numbers,  n  through  m,  where  n  is  less  than  m. 
user        All  messages  from  user. 

/string    All  messages  with  string  in  the  subject  line  (uppercase-lowercase  differences  are  ignored). 
:  c  All  messages  of  type  c,  where  c  is  one  of: 

d     deleted  messages 

n     new  messages 

o     old  messages 

r     read  messages 

u     unread  messages 

Note  that  the  context  of  the  command  determines  whether  this  type  of  message 
specification  makes  sense. 
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Other  arguments  are  usually  arbitrary  strings  whose  usage  depends  on  the  command  involved.  File  names, 
where  expected,  are  expanded  using  normal  shell  conventions  (see  sh(l)).  Special  characters  are  recognized 
by  certain  commands,  and  are  documented  with  the  commands  below. 

At  start-up  time,  mailx  reads  commands  from  a  system-wide  file  (/usr/share/lib/mailx .  rc)  to 
initialize  certain  parameters,  then  from  a  private  start-up  file  ($HOME/  .mailrc)  for  personalized  vari- 
ables. Most  regular  commands  are  legal  inside  start-up  files,  the  most  common  use  being  to  set  up  initial 
display  options  and  alias  lists.  The  following  commands  are  not  legal  in  the  start-up  file:  !,  Copy,  edit, 
followup,  Followup,  hold,  mail,  preserve,  reply,  Reply,  shell,  and  visual.  Any  errors  in  the  start-up  file 
cause  the  remaining  lines  in  the  file  to  be  ignored. 

COMMANDS 

The  foil  owing  is  a  complete  list  of  mailx  commands: 

!  command  Escape  to  the  shell.  See  the  description  of  the  SHELL  environment  variable  below. 

#  comment  Null  command  (comment).  Useful  in  .mailrc  files. 

=  Print  the  current  message  number. 

?  Print  a  summary  of  commands. 

<new-line>  Advance  to  next  message  and  print.  If  this  is  the  first  command  entered,  the  first 

unread  message  is  printed.  (To  read  the  current  message,  useprint.) 

alias  alias  name... 
group  alias  name... 

Declare  an  alias  for  the  given  names.  The  names  are  substituted  when  alias  is  used 
as  a  recipient.  Useful  inthe  .mailrc  file. 

alternates  name... 

Declares  a  list  of  alternate  names  for  your  login.  When  responding  to  a  message, 
these  names  are  removed  from  the  list  of  recipients  for  the  response.  With  no  argu- 
ments, alternates  prints  the  current  list  of  alternate  names.  See  also  allnet 
under  environment  variables. 

cd  [directory] 

chdir  [directory]     Change  directory.  If  directory  is  not  specified,  $HOMEisused. 

copy  [filename] 

copy  [msglist]  filename 

Copy  messages  to  the  file  without  marking  the  messages  as  saved.  Otherwise 

equivalent  to  the  save  command. 

Copy  [msglist]  Save  the  specified  messages  in  a  file  whose  name  is  derived  from  the  author  of  the 
message  to  be  saved,  without  marking  the  messages  as  saved.  Otherwise  equivalent 
to  the  Save  command. 

delete  [msglist]  Delete  messages  from  the  mailbox.  If  autoprint  is  set,  the  next  message  after  the 
last  one  deleted  is  printed  (see  en  vi  ronm  ent  variables).  Seealsodp. 

discard  [header-field  ...] 

ignore  [header-field  ...] 

Suppresses  printing  of  the  specified  header  fields  when  displaying  messages  on  the 
screen.  Examples  of  header  fields  to  ignore  are  "status"  and  "cc."  The  fields  are 
included  when  the  message  is  saved.  The  Print  and  Type  commands  override  this 
command. 

dp[  msglist] 

dt[msglist]  Delete  the  specified  messages  from  the  mailbox  and  print  the  next  message  after  the 

last  one  deleted.  Roughly  equivalent  to  a  delete  command  followed  by  a  print  com- 
mand. 

echo  string  ...        Echo  the  given  string  or  strings  (similar  to  echo  -  see  echo(l)). 

edit  [msglist]  Edit  the  given  messages.  The  messages  are  placed  in  a  temporary  file  and  the  EDI- 
TOR variable  is  used  to  get  the  name  of  the  editor  (see  environment  variables). 
Default  editor  is  ed  (see  ed(l)). 

exit 
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xit  Exit  from  mailx,  without  changing  the  mailbox.  No  messages  are  saved  in  the  mbox 

(see  also  quit). 

file  [filename] 

folder  [filename]  Quit  from  the  current  file  of  messages  and  read  in  the  specified  file.  Several  special 
characters  are  recognized  when  used  as  file  names,  and  substitutions  are  made  as  fol- 
lows: 

%  the  current  mailbox. 

%  user      the  mai  I  box  for  user . 
#  the  previous  file. 

&  the  current  mbox. 


Default  file  is  the  current  mailbox. 


folders 


Print  the  names  of  the  files 

ENVIRONMENT  VARIABLES). 


n  the  directory  set  by  the  folder  variable  (see 


followup  [message] 


Respond  to  a  message  and  record  the  response  in  a  file  whose  name  is  derived  from 
the  author  of  the  message.  Overrides  the  record  variable,  if  set.  See  also  the  Fol- 
lowup, Save,  and  Copy  commands  and  outfolder  (see  environment  vari- 
ables). 

Followup  [msglist]  Respond  to  the  first  message  in  the  msglist,  sending  the  message  to  the  author  of 
each  message  in  the  msglist.  The  subject  line  is  extracted  from  the  first  message  and 
the  response  is  recorded  in  a  file  whose  name  is  derived  from  the  author  of  the  first 
message.  See  also  the  followup,  Save,  and  Copy  commands  and  outfolder  (see 

ENVIRONMENT  VARIABLES). 


from  [msglist] 

group  alias  name 
alias  alias  name.. 


Print  the  header  summary  for  the  specified  messages. 


Declare  an  alias  for  the  given  names.  The  names  are  substituted  when  alias  is  used 
as  a  recipient.  Useful  in  the  .mailrc  file. 

headers  [message]  Prints  the  page  of  headers  which  includes  the  message  specified.  The  screen  vari- 
able sets  the  number  of  headers  per  page  (see  environment  variables).  See  also 
the  z  command. 


help 


Prints  a  summary  of  commands. 


hold  [msglist] 

preserve  [msglist]  Holds  the  specified  messages  in  the  mailbox. 

if  sir 

mai  I -commands 
else 

mai  I -commands 
endif 


Conditional  execution,  where  s  executes  the  accompanying  mai  I -commands,  up  to  an 
else  or  endif  if  the  program  is  in  send  mode,  and  r  causes  the  accompanying  mail- 
commands  to  be  executed  only  in  receive  mode.  I  ntended  for  use  in  .mailrc  files. 


ignore  header-field 

discard  header-field  ... 

Suppresses  printing  of  the  specified  header  fields  when  displaying  messages  on  the 
screen.  Examples  of  header  fields  to  ignore  are  status  and  cc.  All  fields  are 
included  when  the  message  is  saved.  The  Print  and  Type  commands  override  this 
command. 

list  Prints  all  commands  available.  No  explanation  is  given, 

mail  name...  Mail  a  message  to  the  specified  users. 

mbox  [msglist]  Arrange  for  the  given  messages  to  end  up  in  the  standard  mbox  save  file  when 
mailx  terminates  normally.  See  MBOX  description  under  environment  vari- 
ables for  a  description  of  this  file.  See  also  the  exit  and  quit  commands. 

next  [message]  Go  to  next  message  matching  message.  A  msglist  can  be  specified,  but  in  this  case  the 
first  valid  message  in  the  list  is  the  only  one  used.  This  is  useful  for  jumping  to  the 
next  message  from  a  specific  user  since  the  name  would  be  interpreted  as  a  command 
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in  the  absence  of  a  real  command.  See  the  discussion  of  msglists  above  for  a  descrip- 
tion of  possible  message  specifications. 

pipe  [msglist]  [command] 

|  [msglist]  [command] 

Pipe  messages  in  msglist  through  the  specified  command.  Each  message  is  treated  as 
if  it  were  read.  If  msglist  is  not  specified,  the  current  message  is  used.  If  command  is 
not  specified,  the  command  specified  by  the  current  value  of  the  cmd  variableis  used. 
If  msglist  isspecified,  command  must  also  be  specified.  If  the  page  variableis  set,  a 
formfeed  character  isinserted  after  each  message  (see  environ  me  NT  variables). 


preserve  [msglist] 
hold  [msglist] 

Print  [msglist] 
Type  [msglist] 

print  [msglist] 
type  [msglist] 


Preserve  the  specified  messages  i  n  the  mai  I  box. 

Print  the  specified  messages  on  the  screen,  including  all  header  fields, 
suppression  of  fields  by  the  ignore  command. 


Overrides 


quit 


Reply  [msglist] 
Respond  [msglist] 


reply  [message] 
respond  [message] 


Save  [msglist] 


Print  the  specified  messages.  If  crt  is  set,  messages  longer  than  the  number  of  lines 
specified  by  the  crt  variable  are  paged  through  the  command  specified  by  the 
PAGER  variable.  The  default  command  is  pg  (see  pg(l)),  but  many  users  prefer 
more  (see  more(l)  -  seeENViRONMENT  variables). 

Exit  from  mailx,  storing  messages  that  were  read  in  mbox  and  unread  messages  in 
the  user's  system  mailbox.  Messages  that  have  been  explicitly  saved  in  a  file  are 
deleted. 

Send  a  response  to  the  author  of  each  message  in  the  msglist.  The  subject  line  is 
taken  from  the  first  message.  If  record  is  set  to  a  file  name,  the  response  is  saved 
at  the  end  of  that  file  (see  environment  variables). 

Reply  to  the  specified  message,  including  all  other  recipients  of  the  message.  If 
record  is  set  to  a  file  name,  the  response  is  saved  at  the  end  of  that  file  (see 

ENVIRONMENT  VARIABLES). 

Save  the  specified  messages  in  a  file  whose  name  is  derived  from  the  author  of  the 
first  message.  The  name  of  the  file  is  based  on  the  author's  name  with  all  network 
addressing  stripped  off.  See  also  the  Copy,  followup,  and  Followup  commands  and 

outf older  (SeeENViRONMENT VARIABLES). 

save  [filename] 

save  [msglist]  filename 

Save  the  specified  messages  in  the  given  file.  The  file  is  created  if  it  does  not  exist. 
The  message  is  deleted  from  the  mailbox  when  mailx  terminates  unless  keep- 
save  is  set  (seeENViRONMENT  variables  and  the  exit  and  quit  commands). 

set 

set  name 

set  name=string 

set  name=number  Define  a  variable  called  name.  The  variable  can  be  given  a  null,  string,  or  numeric 
value.  Set  by  itself  prints  all  defined  variables  and  their  values  (see  environment 
variables  for  detailed  descriptions  of  the  mailx  variables). 

Invoke  an  interactive  she!  I  (see  SHELL  under  environment  variables). 

Print  the  size  in  characters  of  the  specified  messages. 

Read  commands  from  the  given  file  and  return  to  command  mode. 

Print  the  top  few  lines  of  the  specified  messages.  If  the  toplines  variable  is  set,  it 
is  interpreted  as  the  number  of  lines  to  print  (see  environment  variables).  The 
default  is  5. 


shell 

size  [msglist] 
source  filename 
top  [msglist] 

touch  [msglist] 
Type  [msglist] 


Touch  the  specified  messages.  If  any  message  in  msglist  is  not  specifically  saved  in  a 
file,  it  is  placed  in  the  mbox  upon  normal  termination.  See  exit  and  quit. 


Section  1-502 


-5- 


HP-UX  Release  Hi:  December  2000 


mailx(l) 


mailx(l) 


Print  [msglist] 

type  [msglist] 
print  [msglist] 


unalias  alias 
undelete  [msglist] 

unset  name.  .  . 
version 

visual  [msglist] 


Print  the  specified  messages  on  the  screen,  including  all  header  fields.  Overrides 
suppression  of  fields  by  the  ignore  command. 

Print  the  specified  messages.  If  crt  is  set,  messages  longer  than  the  number  of  lines 
specified  by  the  crt  variable  are  paged  through  the  command  specified  by  the 
PAGER  variable.  The  default  command  is  pg(l)  but  many  users  prefer  more(l)  (see 

ENVIRONMENT  VARIABLES). 

Discard  the  specified  alias  names. 

Restore  the  specified  deleted  messages.  Restores  only  messages  that  were  deleted  in 
the  current  mail  session.  If  autoprint  is  set,  the  last  message  of  those  restored  is 
printed  (seeENViRONMENT variables). 

Cause  the  specified  variables  to  be  erased.  If  the  variable  was  a  shell  variable 
imported  from  the  execution  environment,  it  cannot  be  erased. 

Prints  the  current  version  and  release  date. 

Edit  the  given  messages  with  a  screen  editor.  The  messages  are  placed  in  a  tem- 
porary file  and  the  VISUAL  variable  is  used  to  get  the  name  of  the  editor  (see 

ENVIRONMENT  VARIABLES). 


write  [msglist]  filename 

Write  the  given  messages  on  the  specified  file,  except  for  the  header  (the  "From 
line)  and  trailing  blank  line.  Otherwise  equivalent  to  the  save  command. 


xit 
exit 

z[+|-] 


Exit  from  mailx,  without  changing  the  mailbox.  No  messages  are  saved  in  the  mbox 
(see  also  quit). 

Scroll  the  header  display  forward  or  backward  one  screen-full.  The  number  of 
headers  displayed  is  set  by  the  screen  variable  (see  environ  me  NT  variables). 


TILDE  ESCAPES 

The  following  commands  can  be  used  only  when  in  input  mode,  by  beginning  a  line  with  the  tilde  escape 
character  (~).  See  escape  (envi  ronment  variables)  for  changing  this  special  character. 

~  !  command  Escape  to  the  shell. 

Simulateend  of  file  (terminate  message  input). 

~ :  mail -command 

~_  mail-command  Perform  the  command-level  request.  Valid  only  when  sending  a  message  while  read- 
ing mail. 

~?  Print  a  summary  of  tilde  escapes. 

~A  I  nsert  the  autograph  string  Sign  i nto  the  message  (see  en vi  ronm ent  variables). 

~a  I  nsert  the  autograph  string  sign  i  nto  the  message  (see  en  vi  ronm  ent  variables). 

~b  name...  Add  nameto  the  blind  carbon  copy  (Bcc)  list. 

~c  name...  Add  nameto  the  carbon  copy  (Cc)  list. 

~d  Readinthe  dead. letter  file.  See  DEAD  (under  environment  variables)  for  a 

description  of  this  file. 

~e  Invoke  the  editor  on  the  partial  message.  Also  see  the  EDITOR  environment  vari- 

able description  below. 

~f  [msglist]  Forward  the  specified  messages.  The  messages  are  inserted  into  the  message  without 

alteration. 

~h  Prompt  for  Subject  line  and  To,  Cc,  and  Bcc  lists.  If  the  field  is  displayed  with  an  ini- 

tial value,  it  can  be  edited  as  if  you  had  just  typed  it. 

~i  string  I  nsert  the  valueof  the  named  variableinto the  text  of  the  message.  For  example,  ~A 

is  equivalent  to  ~i  Sign. 

~m  [msglist]  Insert  the  specified  messages  into  the  letter,  shifting  the  new  text  to  the  right  one  tab 

stop.  Valid  only  when  sending  a  message  while  reading  mail. 


HP-UX  Release  Hi:  December  2000 


Section  1-503 


mailx(l) 


mailx(l) 


p 

~q 

~R  name  ... 

"r  filename 
~<  filename 
"< !  command 

~s  string  ... 
~t  name  ... 
~v 

~w  filename 
~x 

"  I  command 


Print  the  message  being  entered. 

Quit  (terminate)  input  mode  by  simulatingan  interrupt.  If  the  body  of  the  message  is 
not  null,  the  partial  message  is  saved  in  dead,  letter .  See  the  description  of  the 
DEAD  environment  variable  below  for  a  description  of  this  file. 

Add  name  to  the  Reply-To  list. 


Read  in  the  specified  file.  If  the  argument  begins  with  an  exclamation  point  (  !  ),  the 
rest  of  the  string  is  assumed  to  be  an  arbitrary  shell  command  and  is  executed,  with 
the  standard  output  inserted  into  the  message. 

Set  the  subject  line  to  string. 

Add  the  given  names  to  the  To  list. 

Invoke  a  preferred  screen  editor  on  the  partial  message.  Also  see  the  VISUAL 
environment  variable  description  below. 

Write  the  partial  message  onto  the  given  file,  without  the  header. 

Exit  as  with  ~q  except  the  message  is  not  saved  in  dead. letter. 

Pipe  the  body  of  the  message  through  the  given  command.  If  command  returns  a  suc- 
cessful exit  status,  the  output  of  the  command  replaces  the  message. 


ENVIRONMENT  VARIABLES 

Thefollowing  variables  are  internal  mailx  program  variables.  They  can  be  imported  from  the  execution 
environment  or  set  by  the  set  command  at  any  time.  The  unset  command  can  be  used  to  erase  variables. 

allnet  All  network  names  whose  login  names  match  are  treated  as  identical.  This  causes  the 

msglist  message  specifications  to  behave  similarly.  Default  is  noallnet .  See  also 
the  alternates  command  and  the  metoo  variable. 


append 

askbcc 

askcc 

asksub 

autoprint 

bang 

charset=charset 

cmd=command 
conv=  con  versi  on 

crt= number 

DEAD=filename 

debug 

dot 


Upon  termination,  append  messages  to  the  end  of  the  mbox  file  instead  of  inserting 
them  at  the  beginning  of  the  file.  Default  is  noappend. 

Prompt  for  the  Bcc  list  after  the  message  is  entered.  Default  is  noaskbcc . 

Prompt  for  the  Cc  list  after  the  message  is  entered.  Default  isnoaskcc. 

Prompt  for  a  subject  if  it  is  not  specified  on  the  command  line  with  the  -s  option. 
Enabled  by  default. 

Enable  automatic  printing  of  messages  after  delete  and  undelete  commands.  Default 
isnoautoprint . 

Enablespecial-case  treatment  of  exclamation  points  (!)  in  shell  escape  command  lines 
asinvi(l).  Default  is nobang. 

Set  the  default  character-set.  If  none  is  specified,  mailx  will  attempt  to  use  the 
value  of  LANG  to  look  up  the  system  default  for  the  user's  locale.  If  that  is  unsuccess- 
ful, the  default  value  of  us-ascii  will  be  used. 

Set  the  default  command  for  thepipe  command.  No  default  value. 

Convert  UUCP  addresses  to  the  specified  address  style.  The  only  valid  conversion 
currently  supported  is  internet,  which  requires  a  mail  delivery  program  conforming  to 
theRFC822  standard  for  electronic  mail  addressing.  Conversion  is  disabled  by  default. 
See  also  sendmail  and  the  -U  command-lineoption. 

Pipe  messages  having  more  than  number  lines  through  the  command  specified  by  the 
valueofthe  PAGER  variable  pg  by  default  (see  pg(l)).  Disabled  by  default. 

The  name  of  the  file  in  which  to  save  partial  letters  in  case  of  untimely  interrupt  or 
delivery  errors.  Default  is  $HOME/dead.  letter. 

Enable  verbose  diagnostics  for  debugging.  Messages  are  not  delivered.  Default  is 
nodebug . 

When  processing  input  from  a  terminal,  interpret  an  ASCII  period  character  on  a  line 
by  itself  as  end-of-file.  Default  is  nodot . 
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~e  command  is  used.  Default  is  ed  (see 


EDlTOR=  command  The  command  to  run  when  the  edit  or 
ed(l)). 

encoding=  encodi  ng 

Set  the  default  encoding  to  be  used  when  8-bit  characters  are  present.  Allowable 
values  are  quoted-printable,  base64  and  8bit.  The  short-hand  q-p  is  also  acceptable  for 
quoted-printable.  The  default  value  will  be  determined  based  upon  the  value  of 
charset .  A  value  of  8bit  means  not  to  encode. 


escape=c 
folder=  directory 


header 
hold 

ignore 

ignoreeof 

keep 

keepsave 
MBOX=filename 

metoo 


Substitute  c  for  the  ~  escape  character. 

The  directory  for  saving  standard  mail  files.  User  specified  file  names  beginning  with 
a  plus  (+)  are  expanded  by  preceding  the  file  name  with  this  directory  name  to  obtain 
the  real  file  name.  If  directory  does  not  start  with  a  slash  ( /  ),  $home  is  used  as  a 
prefix.  There  is  no  default  for  the  folder  variable.  See  also  outf  older  below. 

Enable  printing  of  the  header  summary  when  entering  mailx.  Enabled  by  default. 

Preserve  all  messages  that  are  read  in  the  system  mailbox  instead  of  putting  them  in 
the  standard  mbox  save  file.  Default  is  nohold. 

Ignore  interrupts  while  entering  messages.  Useful  when  communicating  over  noisy 
dial-uplines.  Default  is noignore. 

Ignore  end-of-file  during  message  input.  I  nput  must  be  terminated  by  a  period  (.)  on 
a  line  by  itself  or  by  the  ~  .  command.  Default  is  noignoreeof .  See  also  dot 
above. 

When  the  mailbox  is  empty,  truncate  it  to  zero  length  instead  of  removing  it.  Dis- 
abled by  default. 

Keep  messages  that  have  been  saved  in  other  files  in  the  system  mailbox  instead  of 
deleting  them.  Default  isnokeepsave  . 

The  name  of  the  file  to  save  messages  which  have  been  read.  The  xit  command  over- 
rides this  function,  as  does  saving  the  message  explicitly  in  another  file.  Default  is 
$HOME/mbox. 

Usually,  when  a  group  (alias)  containing  the  sender  is  expanded,  the  sender  is 
removed  from  the  expansion.  Setting  this  option  causes  the  sender  to  be  included  in 
the  group.  Default  is  nometoo . 

mimeheader=  val  ue 

To  add  or  disable  Ml  ME  header  when  sending  mail,  "value"  can  be  'yes'  or  'no'. 

LlSTER=command  The  command  (and  options)  to  use  when  listing  contents  of  the  folder  directory. 
The  default  is  ls(l). 

NOMETAMAIL=  val  ue 

To  disable  the  usage  of  metamail  to  read  MIME  messages,  set  the  value  to  TRUE .  By 
default  the  NOMETAMAIL  variableis  not  set. 

onehop  When  responding  to  a  message  that  was  originally  sent  to  several  recipients,  the  other 

recipient  addresses  are  normally  forced  to  be  relative  to  the  originating  author's 
machine  for  the  response.  This  flag  disables  alteration  of  the  recipients'  addresses, 
improving  efficiency  in  a  network  where  all  machines  can  send  directly  to  all  other 
machi  nes  (i  .e.,  one  hop  away). 

outfolder  Cause  the  files  used  to  record  outgoing  messages  to  be  located  in  the  directory 

specified  by  the  folder  variable.  Default  is  nooutf older .  See  folder  above 
and  the  Save,  Copy,  f  ollowup,  and  Followup  commands. 

page  Used  with  the  pipe  command  to  insert  a  form  feed  after  each  message  sent  through 

thepipe.  Default  is nopage. 

PAGER=  command  The  command  to  use  as  a  filter  for  paginating  output.  This  can  also  be  used  to  specify 
the  pager  command-line  options  (for  example,  set  PAGER=  "more  -c").  Default 
is  pg  (see  pg(D),  but  many  users  prefer  more  (see  more(l)). 


prompt=  string 


Set  the  command  modeprompt  to  string.  Default  is  ?. 
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quiet  Refrain  from  printing  the  opening  message  and  version  when  entering  mailx. 

Default  isnoquiet. 

record=filename   Record  all  outgoing  mail  in  filename.  Disabled  by  default.  See  also  outfolder 
above. 

save  Enable  saving  of  messages  in  dead,  letter  on  interrupt  or  delivery  error.  See 

DEAD  for  a  description  of  this  file.  Enabled  by  default. 

screens  number    Set  the  number  of  lines  in  a  screen-full  of  headers  for  the  headers  command. 

sendmail=  command 

Alternate  command  for  delivering  messages.  Default  is  mail  (see  mail  (1)). 

Wait  for  background  mailer  to  finish  before  returning.  Default  is  nosendwait . 

The  name  of  a  preferred  command  interpreter.  Default  is  the  user's  login  program 
(see  passwd(4),  shells(4):  and  chsh(l)).  Note:  in  the  unusual  case  that  a  user's  login 
program  is  a  script  file  from  which  mailx  is  executed,  rather  than  a  shell,  then 
mailx  requires  that  the  user  explicitly  set  SHELL=/ usr/ bi n/ sh  in  his  or  her 
$HOME/ .mailrc  file. 

When  displaying  the  header  summary  and  the  message  is  from  you,  print  the 
recipient's  name  instead  of  the  author's  name. 

The  variablethat  is  inserted  into  the  text  of  a  message  when  the  ~a  (autograph)  com- 
mand is  given.  No  default  (see  also  ~i  under  ilde  escapes). 

Thevariableinserted  into  the  text  of  a  message  when  the  ~A  command  is  given.  No 
default  (see also  ~i  (tilde  escapes)). 

When  SMARTMA I LER  is  set,  various  commands  use  the  From:  line  instead  of  the 
default  From  line. 

toplines=  number 

The  number  of  lines  of  header  to  print  with  the  top  command.  Default  is  5. 
VlSUAL=command  The  name  of  a  preferred  screen  editor.  Default  is  vi  (seevi(l)). 

EXTERNAL  INFLUENCES 
Environment  Variables 

The  following  are  environment  variables  taken  from  the  execution  environment  and  are  not  alterable 
within  mailx. 


sendwait 
SHELL=  command 


showto 

sign=string 

Sign=string 

SMARTMA I LER 


HOME 


MAILRC 

LC_COLLATE 
LC_CTYPE 


LC_TIME 


TMPDIR 


The  user's  home  directory.  This  is  usually  the  current  directory  immediately  after 
login. 

The  nameof  the  mailer  start-up  file.  Default  is  $HOME/  .mailrc . 

LC_COLLATE  and  LC_CTYPE  influence  mailx  when  the  command  interpreter 
(see  shell  below)  is  invoked.  To  determine  the  behavior  of  LC_COLLATE  and 
LC_CTYPE,  see  the  corresponding  shell  manual  entry  for  the  applicable  command 
interpreter 

LC_TIME  determines  the  format  and  contents  of  the  date  and  time  strings  displayed. 
If  LC_TIME  is  not  specified  in  the  environment,  or  is  set  to  the  empty  string,  the 
value  of  LANG  is  used  as  a  default.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationaliza- 
tion variable  contains  an  invalid  setting,  mailx  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

When  set,  the  TMPDIR  environment  variable  specifies  a  directory  to  be  used  for  tem- 
porary files,  overriding  the  default  directory  /tmp. 


I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported  within  mail  text.  Headers  are  restricted  to  char- 
acters from  the  7-bit  usascii  character  code  set  (see  ascii  (5)). 
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WARNINGS 

Where  command  isshown  as  valid,  arguments  are  not  always  allowed.  Experimentation  is  recommended. 
I  nternal  variables  imported  from  the  execution  environment  cannot  be  unset. 

Thefull  internet  addressing  is  not  fully  supported  by  mailx.  The  new  internationalization  standards  need 
some  ti  me  to  settl  e  down. 

mail(l),  the  standard  mail  delivery  program,  treats  a  line  consisting  solely  of  a  dot  (.)  as  the  end  of  the 
message. 

Using  two  separate  mail  programs  to  access  the  same  mail  file  simultaneously  (usually  inadvertently  from 
two  sepa rate  wi  n dows)  can  cau se  u n predi  ctabl  e  resu I ts. 


FILES 


/var/mail/ 


Post  office  directory  (mode  775,  group  id  mail) 

System  mailbox  for  user  (mode  660,  owned  by  user, group  id  mail) 

Personal  start-up  file 

Global  start-up  file 

Secondary  storage  file 

Temporary  files 


/var/mail/  user 
$HOME/ . mailrc 


/usr/ share/lib/mailx . rc 

$HOME/mbox 

/  tmp /R  [emqsx  ]  * 


SEE  ALSO 

mail(l),  pg(l),  ls(l). 


STANDARDS  CONFORMANCE 

mailx:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

make  -  maintain,  update,  and  regenerate  groups  of  programs 
SYNOPSIS 

make  [-f  makefile]  [-bBdeiknpPqrsStuw]  [macro_name=value]  [names] 

DESCRIPTION 

Makefile  Structure 

A  makefile  can  contain  four  different  kinds  of  lines:  target  lines,  shell  command  lines,  macro  definitions, 
and  includelines. 

TARGET  LINES 

Target  lines  consist  of  a  blank-separated,  non-null  list  of  targets,  followed  by  a  colon  (:)  or  double  colon 
(:  : ),  followed  by  a  (possibly  null)  list  of  prerequisite  files  called  dependents.  Pattern  Matching  Notation 
(see  regexp(5))  is  supported  for  the  generation  of  file  names  as  dependents. 

SHELL  COMMAND  LINES 

Text  following  a  semicolon  (; )  on  a  target  line,  and  all  following  lines  that  begin  with  a  tab  are  shell  com- 
mands to  be  executed  to  update  the  target  (see  the  Environment  section  below  about  SHELL).  The  first 
line  that  does  not  begin  with  a  tab  or  #  begins  a  new  target  definition,  macro  definition,  or  include  line. 
Shell  commands  can  be  continued  across  lines  by  using  a  <backsl ash xnew-line> sequence. 

Target  lines  with  their  associated  command  lines  are  called  rules. 
MACROS 

Lines  of  the  form  stringl  =  string2  are  macro  definitions.  Macros  can  be  defined  anywhere  in  the 
makefile,  but  are  usually  grouped  together  at  the  beginning,  stringl  is  the  macro  name;  string2  is  the 
macro  value.  string2  is  defined  as  all  characters  up  to  a  comment  character  or  an  unescaped  new-line. 
Spaces  and  tabs  immediately  to  the  left  and  right  of  the  =  are  ignored.  Subsequent  appearances  of 
$  (stringl)  anywhere  in  the  makefile  (except  in  comments)  are  replaced  by  string2.  The  parentheses  are 
optional  if  a  single  character  macro  name  is  used  and  there  is  no  substitute  sequence.  An  optional  substi- 
tute sequence,  $  (stringl  [:substl=[subst2]])  can  be  specified,  which  causes  all  nonoverlapping 
occurrences  of  substl  at  the  end  of  substrings  in  the  value  of  stringl  to  be  replaced  by  subst2.  Substrings  in 
a  macro  valueare  delimited  by  blanks,  tabs,  new-line  characters,  and  beginnings  of  lines.  For  example,  if 

OBJS  =  filel.o  file2.o  file3.o 

then 

$(OBJS: .o=.c) 

eval  uates  to 

f ilel . c  f ile2 . c  file3.c 

Macro  values  can  contain  references  to  other  macros  (see  WARNINGS): 

ONE  =1 

TWELVE  =  $(ONE)2 

The  value  of  $  (TWELVE)  is  set  to  $  (ONE)  2  but  when  it  is  used  in  a  target,  command,  or  include  line,  it 
is  expanded  to  12.  If  the  value  of  ONE  is  subsequently  changed  by  another  definition  further  down  in  the 
makefile  or  on  the  command  line,  any  references  to  $  (TWELVE)  reflect  this  change. 

Macro  definitions  can  also  be  specified  on  the  command  line  and  override  any  definitions  in  the  makefile. 

(XPG4  only.  Macros  on  the  command  line  are  added  to  the  MAKEFLAGS  environment  variable.  Macros 
defined  in  the  MAKEFLAGS  environment  variable,  but  without  any  command  line  macro,  adds  the  macro  to 
the  environment  overwriting  any  existing  environment  variableof  the  same  name.) 

Certain  macros  are  automatically  defined  for  make  (see  Built-in  Macros).  See  the  Environment  section  for 
a  discussion  of  the  order  in  which  macro  definitions  are  treated. 

The  value  assigned  to  a  macro  can  be  overridden  by  a  conditional  macro  definition.  A  conditional  macro 
definition  takes  on  the  form  target  :=  stringl  =  string2.  When  the  target  line  associated  with  target  is 
being  processed,  the  macro  value  specified  in  the  conditional  macro  definition  is  in  effect.  If  stringl  is  pre- 
viously defined,  the  new  value  of  stringl  will  override  the  previous  definition.  The  new  value  of  stringl 
takes  effect  when  target  or  any  dependents  of  target  are  being  processed. 
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INCLUDE  LINES 

If  the  string  include  appears  as  the  first  seven  letters  of  a  line  in  a  makefile,  and  is  followed  by  one  or 
more  space  or  tab  characters,  the  rest  of  the  line  is  assumed  to  be  a  file  name  and  is  read  and  processed  by 
the  current  invocation  of  make  as  another  makefile  after  any  macros  in  the  filename  have  been  expanded. 

The  default  behaviour  of  make  is  to  use  .DEFAULT  built-in  target,  if  target  does  not  have  explicit  com- 
mands associated  with  itand  .  DEFAULT  target  isdefined.  See  the  Bui  lt-1  n  Targets  Section. 

General  Description 

make  executes  commands  previously  placed  in  a  makefile  to  update  one  or  more  target  names.  Target 
names  are  typically  names  of  programs.  If  no  -f  option  is  specified,  the  filenames  makefile, 
Makefile,  s.  makefile,  SCCS/s  .makefile,  s.  Makefile  and  SCCS/s  .Makefile  are  tried  in 
that  order.  If  -f  -  is  specified,  the  standard  input  is  used.  More  than  one  -f  option  can  be  specified. 
The  makefile  arguments  are  processed  in  the  order  specified.  A  space  between  the  -f  and  the  filename 
must  be  present,  and  multiple  makefile  names  must  each  have  their  own  -f  option  precedi ng  them.  The 
contents  of  a  makefile  override  the  built-in  rules  and  macros  if  they  are  present. 

If  no  target  names  are  specified  on  the  command  line,  make  updates  the  first  target  in  the  (first)  makefile 
that  is  not  an  inference  rule.  A  target  is  updated  only  if  it  depends  on  files  that  are  newer  than  the  target. 
Missing  files  a  re  deemed  to  be  out-of-date.  All  dependents  of  a  target  are  recursively  updated,  if  necessary, 
before  the  target  is  updated.  This  effects  a  depth-first  update  of  the  dependency  tree  for  the  target. 

If  a  target  does  not  have  any  dependents  specified  after  the  separator  on  the  target  line  (explicit  depen- 
dents), any  shell  commands  associated  with  that  target  are  executed  if  the  target  i s  out-of-date. 

A  target  line  can  have  either  a  single  or  double  colon  between  the  target  name  or  names  and  any  explicit 
dependent  names.  A  target  name  can  appear  on  more  than  one  target  line,  but  all  of  those  lines  must  be  of 
the  same  (single-  or  double-colon)  type.  For  the  usual  single-colon  case,  at  most  one  of  these  target  lines 
can  have  explicit  commands  associated  with  it.  If  the  target  is  out-of-date  with  any  of  its  dependents  on 
any  of  the  lines,  the  explicit  commands  are  executed,  if  they  are  specified,  or  else  a  default  rule  can  be  exe- 
cuted. For  the  double-colon  case,  explicit  commands  can  be  associated  with  more  than  one  of  the  target 
lines  containing  the  target  name;  if  the  target  is  out-of-date  with  any  of  the  dependents  on  a  particular  line, 
the  commands  for  that  line  are  executed.  A  built-in  rulemay  also  be  executed. 

Target  lines  and  their  associated  shell  command  lines  are  also  referred  to  as  rules.  Hash  marks  (#)  and 
new-line  characters  surround  comments  anywhere  in  the  makefile  except  in  rules.  Comments  in  the  rules 
depend  on  the  setti  ng  of  the  SHELL  macro. 

The  foil  owing  makefile  says  that  pgm  depends  on  two  files:  a.  o  and  b.  o,  and  that  they  in  turn  depend  on 
their  corresponding  source  files  (a.  c  and  b.  c)  and  a  common  file  incl  .h: 

OBJS  =  a.o  b.o 

pgm:    $ (OBJS) 

cc  $(OBJS)    -o  pgm 

a.  o:    incl.h  a.c 

cc  -c  a.c 

b.  o:    incl.h  b.c 

cc  -c  b.c 

Command  lines  are  executed  one  at  a  time,  each  by  its  own  shell.  Each  command  line  can  have  one  or 
more  of  the  foil  owing  prefixes:  -,  @  or +.  These  prefixes  are  explained  below. 

Commands  returning  non-zero  status  normally  termi nate make .  The-i  option  or  the  presence  of  the  spe- 
cial target  .  IGNORE  in  the  makefile  cause  make  to  continue  executing  the  makefile  regardless  of  how 
many  command  lines  cause  errors,  although  the  error  messages  are  still  printed  on  standard  output.  If  -  is 
present  at  the  beginning  of  a  command  line,  any  error  returned  by  that  line  is  printed  to  standard  output 
but  make  does  not  terminate.  The  prefix  -  can  be  used  to  selectively  ignore  errors  in  a  makefile.  If  the  -k 
option  is  specified  and  a  command  line  returns  an  error  status,  work  is  abandoned  on  the  current  target, 
but  continues  on  other  branches  that  do  not  depend  on  that  target.  If  the  -k  option  is  present  in  the 
MAKEFLAGS  environment  variable,  processing  can  be  returned  to  the  default  by  specifying  the  -S  option. 

The  -n  option  specifies  printing  of  a  command  line  without  execution.  However,  if  the  command  line  has 
the  string  $  (MAKE)  or  $  {make}  in  it  or  +  as  a  prefix,  the  line  is  always  executed  (see  discussion  of  the 
MAKEFLAGS  macro  under  Environment).  The  -t  (touch)  option  updates  the  modified  date  of  a  file 
without  executing  any  commands. 
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A  command  line  is  normally  printed  before  it  is  executed,  but  if  the  line  has  a  @at  the  beginning,  printing 
is  suppressed.  The  -s  option  or  the  presence  of  the  special  target  .  SILENT :  in  the  makefile  suppresses 
printing  of  all  command  lines.  The@can  be  used  to  selectively  turn  off  printing.  Everything  printed  by 
make  (except  the  initial  tab)  is  passed  directly  to  the  shell  without  alteration.  Thus, 

echo  a\ 
b 

produces 
ab 

just  as  the  shell  would. 

The  -b  option  allows  old  makefiles  (those  written  for  the  old  version  of  make)  to  run  without  errors.  The 
old  version  of  make  assumed  that  if  a  target  did  not  have  any  explicit  commands  associated  with  it,  the 
user  intended  the  command  to  be  null,  and  would  not  execute  any  .  DEFAULT  rule  that  might  have  been 
defined.  The  current  version  of  make  operates  in  this  mode  by  default.  However,  the  current  version  of 
make  provides  a  -B  option  which  turns  this  mode  off  so  that  if  a  target  does  not  have  explicit  commands 
associated  with  it  and  a  .  DEFAULT  rule  is  defined,  the  .DEFAULT  rule  is  executed.  Note  that  the -b  and 
-B  options  have  no  effect  on  the  search  and  possible  location  and  execution  of  an  appropriate  inference  rule 
for  the  target.  Thesearch  for  a  built-in  inference  ruleother  than  .DEFAULT  is  always  performed. 

The  signals  SIGINT,  SIGQUIT,  SIGHUP,  and  SIGTERM  (see  signal (5))  cause  the  target  to  be  deleted 
unless  the  target  depends  on  the  special  name  .PRECIOUS. 

Options 

Thefollowing  is  a  brief  description  of  all  options  and  some  special  names.  Options  can  occur  in  any  order. 
They  can  be  specified  separately,  or  together  with  one  -,  except  for  the  -f  option. 


-b  Compatibility  mode  for  old  (Version  7)  makefiles.  Thisoption  isturned  on  by  default. 

-B  Turn  off  compatibility  mode  for  old  (Version  7)  makefiles. 

-d  Debug  mode.  Print  out  detailed  information  on  files  and  times  examined.  (This  is  very  ver- 

boseand  is  intended  for  debugging  the  make  command  itself.) 

-e  Environment  variables  override  assignments  within  makefiles  . 


-f  makefile  Description  file  name,  referred  to  as  the  makefile.  A  file  name  of  -  denotes  the  standard 
input.  The  contents  of  the  makefile  override  the  built-in  rules  and  macros  if  they  are 
present.  Note  that  the  space  between  -f  and  makefile  must  be  present.  Multiple 
instances  of  this  option  are  allowable  (except  for  -f  -),  and  are  processed  in  the  order 
specified. 

-i  Ignore  error  codes  returned  by  invoked  commands.  This  mode  is  also  entered  if  the  special 

target  name  .  IGNORE  appears  in  the  makefile. 

-k  When  a  command  returns  nonzero  status,  abandon  work  on  the  current  entry,  but  continue 

on  other  branches  that  do  not  depend  on  that  target.  This  is  the  opposite  of  -S.  If  both  -k 
and  -S  are  specified,  the  last  one  specified  is  used. 

-n  N o  execute  mode.  Print  commands,  but  do  not  execute  them.  Even  lines  beginning  with  an 

@areprinted.  However,  lines  that  contain  the  string  $  (MAKE)  or  ${  MAKE}  or  that  have 
+  as  a  prefix  to  the  command  are  executed. 

-p  Write  to  standard  output  the  complete  set  of  macro  definitions  and  target  descriptions. 

-P  Update  in  parallel  more  than  one  target  at  a  time.  The  number  of  targets  updated  con- 

currently is  determined  by  the  environment  variable  PARALLEL  and  the  presence  of 
.MUTEX  directives  in  makefile. 

-q  Question.  The  make  command  returns  a  zero  or  non-zero  status  code,  depending  on 

whether  the  target  file  is  or  is  not  up-to-date.  Targets  are  not  updated  with  this  option. 

-r  Clear  suffix  list  and  do  not  use  the  built-in  rules. 

-s  Silent  mode.  Command  lines  are  not  printed  to  standard  output  before  their  execution. 

This  mode  is  also  entered  if  the  special  target  name  .  SILENT  appears  in  the  makefile. 

-S  Terminate  if  an  error  occurs  while  executing  the  commands  to  bring  a  target  up-to-date. 

This  is  the  default  and  the  opposite  of  -k.   If  both  -k  and  -S  are  specified,  the  last  one 
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given  is  used.  This  enables  overriding  the  presence  of  the  k  flag  in  the  MAKEFLAGS 
environment  variable. 

-t  Touch  the  target  files  (causing  them  to  be  up-to-date)  rather  than  issue  the  usual  com- 

mands. 

-u  Unconditionally  make  the  target,  ignoring  all  timestamps. 

-w  Suppress  warning  messages.  Fatal  messages  will  not  be  affected. 

[  ma  cron  a  me=va  I  u  e] 

Zero  or  more  command  line  macro  definitions  can  be  specified.  Seethe  Macros  section. 

[names]  Zero  or  more  target  names  that  appear  in  the  makefile.  Each  target  so  specified  is  updated 

by  make.  If  no  names  are  specified,  make  updates  the  first  target  in  the  makefile  that  is 
not  an  inference  rule. 

Parallel  Make 

If  make  is  invoked  with  the  -P  option,  it  tries  to  build  more  than  one  target  at  a  time,  in  parallel.  (This  is 
done  by  using  the  standard  UNIX  system  process  mechanism  which  enables  multiple  processes  to  run 
simultaneously.)  For  the  makefile  shown  in  the  example  in  the  previous  section,  it  would  create  processes 
to  build  a .  o  and  b .  o  in  parallel.  After  these  processes  were  complete,  it  would  build pgm. 

The  number  of  targets  make  will  try  to  build  in  parallel  is  determined  by  the  value  of  the  environment 
variable  PARALLEL.  If  -P  is  invoked,  but  PARALLEL  is  not  set,  then  make  will  try  to  build  no  more  than 
two  targets  in  parallel. 

You  can  use  the  . MUTEX  directive  to  serialize  the  updating  of  some  specified  targets.  This  is  useful  when 
two  or  more  targets  modify  a  common  output  file,  such  as  when  inserting  modules  into  an  archive  or  when 
creating  an  intermediate  file  with  the  same  name,  as  is  done  by  lex  and  yacc.  If  the  makefile  in  the  previ- 
ous section  contained  a  .MUTEX  directive  of  the  form 

.MUTEX:   a.o  b.o 

it  would  prevent  make  from  building  a.o  and  b.o  in  parallel. 

Environment 

All  variables  defined  in  the  environment  (see  environ(5))  are  read  by  make  and  are  treated  and  processed 
as  macro  definitions,  with  the  exception  of  the  SHELL  environment  variable  which  is  always  ignored.  The 
value  of  the  SHELL  environment  variable  will  not  be  used  as  a  macro  and  will  not  be  modified  by  defining 
the  SHELL  macro  in  a  makefile  or  on  the  command  line.  Variables  with  no  definition  or  empty  string 
definitions  are  included  by  make. 

There  are  four  possible  sources  of  macro  definitions  which  are  read  in  the  following  order:  internal 
(default),  current  environment,  the  makefile(s),  and  command  line.  Because  of  this  order  of  processing, 
macro  assignments  in  a  makefile  override  environment  variables.  The-e  option  allows  the  environment  to 
override  the  macro  assignments  in  a  makefile.  Command-line  macro  definitions  always  override  any  other 
definitions. 

TheMAKEFLAGS  environment  variable  is  processed  by  make  on  the  assumption  that  it  contains  any  legal 
input  option  (except  -f,  -p,  and  -d)  defined  for  the  command  line.  TheMAKEFLAGS  variablecan  also  be 
specified  in  the  makefile. 

(XPG4only.  MAKEFLAGS  i n  the  makefile  replaces  the  MAKEFLAGS  environment  variable.  Command  line 
options  have  precedence  over  MAKEFLAGS  environment  variable.) 

If  MAKEFLAGS  is  not  defined  in  either  of  these  places,  make  constructs  the  variable  for  itself,  puts  the 
options  specified  on  the  command  line  and  any  default  options  into  it,  and  passes  it  on  to  invocations  of 
commands.  Thus,  MAKEFLAGS  always  contains  the  current  input  options.  This  proves  very  useful  for 
recursive  makes.  Even  when  the  -n  option  is  specified,  command  lines  containing  the  string  $  (MAKE)  or 
$  {make}  are  executed;  hence,  one  can  perform  a  make  -n  recursively  on  an  entire  software  system  to 
see  what  would  have  been  executed.  Thisispossiblebecausethe-n  isput  into  MAKEFLAGS  and  passed  to 
the  recursive  invocations  of  $  (MAKE)  or  $  {MAKE } .  This  is  one  way  of  debugging  all  of  the  makefiles  for  a 
software  project  without  actual  ly  executi  ng  any  of  the  commands. 

Each  of  the  commands  in  the  rules  is  given  to  a  shell  to  be  executed.  The  shell  used  is  the  shell  command 
interpreter  (see  sh(l)),  or  the  one  specified  in  the  makefile  by  the  SHELL  macro.  To  ensure  the  same  shell 
is  used  each  time  a  makefile  is  executed,  the  line: 


HP-UX  Release  Hi:  December  2000 


_4_ 


Section  1-511 


make(l) 


make(l) 


SHELL=/usr/bin/sh 

or  a  suitableequivalent  should  be  put  in  the  macro  definition  section  of  the  makefile. 

Suffixes 

Target  and/or  dependent  names  often  have  suffixes.  Knowledge  about  certain  suffixes  is  built  into  make 
and  used  to  identify  appropriate  inference  rules  to  be  applied  to  update  a  target  (see  the  section  on  Infer- 
ence Rules).  Thecurrent  default  list  of  suffixes  is: 

.o   .c   .c~    .C   .C~    . cxx   .cxx~    . cpp   .cpp~    . cc  .cc~ 
.y   .y~    .1    .1"    .L    .L~    .  Y    .Y~    .s    .s~    .  sh    .  sh~ 
.h   .h~    .H   .H~      .p   .p~    .f   .  f    .r  .r~ 

These  suffixes  are  defined  as  the  dependents  of  the  special  built-in  target  . SUFFIXES .  This  is  done 
automatically  by  make. 

Additional  suffixes  can  be  specified  in  a  makefile  as  the  dependents  list  for  .  SUFFIXES .  These  additional 
values  are  added  to  the  default  values.  Multiple  suffix  lists  accumulate.  The  order  of  the  suffix  list  is 
significant  (seethe  I  nference  Rules  section).  If  the  user  wishes  to  change  the  order  of  the  suffixes,  he  must 
first  define  .SUFFIXES  with  a  null  dependent  list,  which  clears  the  current  value  for  .SUFFIXES,  and 
then  define  .  SUFFIXES  with  the  suffixes  in  the  desired  order.  The  list  of  suffixes  built  into  make  on  any 
machine  can  be  displayed  by: 

make  -fp  -  2>/dev/null  </dev/null 

The  list  of  built-in  suffixes  incorporated  with  the  definitions  in  a  given  makefile  called  mymakef  ile  can  be 
displayed  by: 

make  -fp  mymakef ile  2>/dev/null  </dev/null 
Inference  Rules 

Certain  target  or  dependent  names  (such  as  those  ending  with  .  o)  have  inferable  dependents  such  as  .  c 
and  .  s,  etc.  If  no  update  commands  for  such  a  name  appear  in  the  makefile,  and  if  an  inferable  dependent 
file  exists,  that  dependent  file  is  compiled  to  update  the  target.  I  n  this  case,  make  has  inference  rules  that 
allow  building  files  from  other  files  by  examining  the  suffixes  and  determining  an  appropriate  inference  rule 
to  use.  There  are  currently  default  inference  rules  defined  for: 

SingleSuffix  Rules 

.  c  .  c~ 

.C   .C~    .cxx   .cxx"    -cpp   .cpp~    . cc  .cc" 
. sh   . sh~ 

•P  -P~ 
.f  .f~ 
.  r   .  r~ 

Double  Suffix  Rules 

.c.o   .c~.o   .c~.c   .c.a  .c~.a 

.Co   .C~.o    .C~.C   .C.a  .C~.a 

.cxx.o    .cxx" .o    .cxx'.cxx    .cxx. a  .cxx'.a 

.cpp.o   .cpp~.o   .cpp~.cpp   .cpp. a  .cpp~.a 

.cc.o   .cc~.o   .cc~.cc   .cc.a  .cc~.a 


s 

o 

.  s 

.  o 

.  s 

.  a 

P 

o 

■P~ 

.  o 

•  p" 

'.p   .p. a 

.p~.a 

f 

o 

.f" 

.  o 

.f" 

'.f  .f.a 

.f.a 

r 

o 

.  r~ 

.  o 

.  r" 

' .  r   .  r .  a 

.  r~  .  a 

y 

o 

•  y" 

.  o 

•  y 

c   . y~ . c 

1 

o 

.i" 

.  o 

.i 

c 

h" 

".h 

H~ 

H 

hxx" . hxx 

.hpp 

C 

o 

.c~ 

.  o 

.c 

a  .C~.a 

L 

C 

.L. 

o 

L~ 

C  .L~.L 

.L~  .o 

Y 

C 

.  Y. 

o 

Y~ 

C  .Y~.Y 

.Y~  .o 

Double  suffix  inference  rules  (.  c  .o)  define  how  to  build  x.  o  from  x.  c.  Single  suffix  inference  rules  ( .  c) 
define  how  to  build  x  from  x.c.  In  effect,  the  first  suffix  is  null.  Single  suffix  rules  are  useful  for  building 
targets  from  only  one  source  file;  e.g.,  shell  procedures  and  simpleC  programs. 
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A  tilde  in  the  above  rules  refers  to  an  SCCS  file  (see  sccsfile(4)).  Thus,  the  rule  .  c~ .  o  would  transform  an 
SCCS  C  source  file  into  an  object  file  (.o).  Since  the  s.  of  the  SCCS  files  is  a  prefix,  it  is  incompatible 
with  make's  suffix  point-of-view.  Hence,  the  tilde  is  a  way  of  changing  any  file  reference  into  an  SCCS  file 
reference. 

A  rule  to  create  a  file  with  suffix  .  o  from  a  file  with  suffix  .  c  is  specified  as  an  entry  with  .  c .  o  as  the  tar- 
get and  no  dependents.  Shell  commands  associated  with  the  target  define  the  rule  for  making  a  .  o  file 
from  a  .  c  file.  Any  target  name  that  has  no  slashes  in  it  and  starts  with  a  dot  is  identified  as  an  inference 
(implicit)  rule  instead  of  a  target  (explicit)  rule.  Targets  with  one  dot  are  single  suffix  inference  rules; 
targets  with  two  dots  are  double  suffix  inference  rules.  Users  can,  in  a  makefile,  define  additional  inference 
rules  and  either  redefine  or  cancel  default  inference  rules. 

Thedefault  inference  rule  for  changinga  .c  file  intoa  .o  filemight  look  likethis: 
.c.o: 

$(CC)    $(CFLAGS)    -c  $< 

and  the  default  inference  rule  for  changing  a  yacc  file  to  a  C  object  file  might  look  likethis: 
.y.o: 

$(YACC)    $  (YFLAGS)  $< 
$(CC)    $(CFLAGS)    -c  y.tab.c 
rm  y . tab . c 
mv  y.tab.o  $@ 

Certain  macros  are  used  in  the  default  inference  rules  to  permit  the  inclusion  of  optional  matter  in  any 
resulting  commands.  For  example,  CFLAGS,  LDFLAGS,  and  YFLAGS  are  used  for  compiler  options  to 
cc(l),  lex(l),  and  yacc(l),  respectively.  LDFLAGS  is  commonly  used  to  designate  linker/loader  options. 
These  macros  are  automatically  defined  by  make  but  can  be  redefined  by  the  user  in  the  makefile. 

The  macro  LIBS  is,  by  convention,  used  to  specify  the  order  of  inclusion  of  any  special  libraries  during  the 
linking  phase  of  compilation.  To  specify  a  particular  order  of  inclusion  for  a  particular  set  of  libraries,  the 
existing  singlesuffix  rulefor  a  .cfile, 

$(CC)    $  (CFLAGS)    $<   $  (LDFLAGS)    -O  $@ 

can  be  redefined  as 

$(CC)    $  (CFLAGS)    $<   $  (LDFLAGS)    -O   $@  $(LIBS) 

as  well  as  defining  LIBS  in  the  makefile. 

There  are  also  some  special  built-in  macros  used  in  the  inference  rules  (@,  <).  See  the  Built-in  Macros  sec- 
tion. 

If  a  target  does  not  have  explicit  dependents,  or  if  a  dependent  does  not  also  have  a  target  that  matches  it 
with  associated  explicit  rules,  make  looks  for  the  first  inference  rule  that  matches  both  the  target's 
(dependent's)  suffix  (which  may  be  null)  and  a  file  which  matches  the  other  suffix  of  the  rule.  Since  it  con- 
ducts this  search  by  going  through  the  list  of  .SUFFIXES  values  front  to  back,  the  order  in  which  .SUF- 
FIXES is  defined  is  significant. 

To  print  out  the  rules  compiled  into  the  make  on  any  machine,  type: 

make  -fp  -  2>/dev/null  </dev/null 

Since  make  defines  an  inference  rule  .c.o,  the  example  in  the  General  Description  section  can  be  rewrit- 
ten more  simply: 

OBJS  =  a.o  b.o 
pgm:    $ (OBJS) 

cc  $(OBJS)    -o  pgm 
$ (OBJS) :  incl.h 

Libraries 

If  a  target  or  dependent  name  contains  parentheses,  it  is  assumed  to  be  an  archive  library,  the  string 
within  parentheses  referring  to  a  member  within  the  library.  Thus  lib(file.o)  and 
$  (LIB)  (file.o)  both  refer  to  an  archive  library  that  contains  file .  o  (this  assumes  the  LIB  macro 
has  been  previously  defined).  The  expression  $  (LIB)  (f  ilel .  o  file2.o)  is  not  valid.  Rules  per- 
taining to  archive  libraries  have  the  form  .  xx .  a  where  xx  is  the  suffix  from  which  the  archive  member  is  to 
be  made.  An  unfortunate  byproduct  of  the  current  implementation  requires  the  xx  to  be  different  from  the 
suffix  of  the  archive  member.  Thus,  one  cannot  have  lib  (file.o)  depend  upon  file.o  explicitly. 
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The  most  common  use  of  the  archive  interface  follows.  Here,  we  assume  the  source  files  are  all  C  type 
source: 

lib:   lib(filel.o)    lib(file2.o)  lib(file3.o) 
@echo  lib  is  now  up-to-date 

.  c .  a : 

$(CC)    -c  $(CFLAGS)  $< 
ar  rv  $@  $*.o 
rm  -f  $*  .  o 

(See  the  section  on  Built-in  Macros  for  an  explanation  of  the  <,  @  and  *  symbols.)  I  n  fact,  the  .  c  .a  rule 
listed  above  is  built  into  make  and  is  unnecessary  in  this  example.  This  rule  is  applied  to  each  dependent 
of  lib  inturn.  Thefollowingexampleaccomplishesthismoreefficiently: 

lib:     lib(filel.o)    lib(file2.o)  lib(file3.o) 
$(CC)    -c  $(CFLAGS)  $(?:.o=.c) 
ar  rv  lib  $? 
rm  $? 

gecho  lib  is  now  up-to-date 
.  c .  a :  ; 

Here  substitution  in  the  macros  is  used.  The  $?  list  is  defined  to  be  the  set  of  object  file  names  (inside 
lib)  whose  C  source  files  are  out-of-date.  The  substitution  sequence  translates  the  .  o  to  .c.  (Unfor- 
tunately, one  cannot  as  yet  transform  to  .  c~;  however,  this  may  become  possible  in  the  future.)  Note  also, 
the  disabling  of  the  .c.a  rule,  which  would  have  created  and  archived  each  object  file,  one  by  one.  This 
particular  construct  speeds  up  archive  library  maintenance  considerably,  but  becomes  very  cumbersome  if 
the  archive  library  contains  a  mix  of  assembly  programs  and  C  programs. 

Archive  members  containing  the  definition  of  a  symbol  are  designated  by  double  parentheses  around  the 
symbol  name,  lib  ( (entryname) ) ,  but  are  otherwise  handled  as  described  above. 

Built-in  Targets 

make  has  knowledge  about  some  special  targets.  These  must  be  specified  in  the  makefile  to  take  effect 
(with  the  exception  of  .  SUFFIXES,  which  is  automatically  set  by  make  but  can  be  changed  by  the  user). 

.  DEFAULT  If  a  file  must  be  made  but  there  are  no  explicit  commands  or  relevant  built-in  rules  for 
it,  the  commands  associated  with  the  target  name  .  DEFAULT  are  used  if  .  DEFAULT 
has  been  defined  in  the  makefile.  .DEFAULT  does  not  have  any  explicit  dependents. 

.  PRECIOUS  Dependents  of  this  target  are  not  removed  when  QUIT,  INTERRUPT ,  TERMINATE , 
or  HANGUP  are  received. 

.SILENT  Same  effect  as  the  -s  option.  No  dependents  or  explicit  commands  need  to  be 
specified. 

.IGNORE  Same  effect  as  the  -i  option.  No  dependents  or  explicit  commands  need  to  be 
specified. 

.SUFFIXES  The  explicit  dependents  of  .SUFFIXES  are  added  to  the  built-in  list  of  known 
suffixes  and  are  used  in  conjunction  with  the  inference  rules.  If  .  SUFFIXES  does  not 
have  any  dependents,  the  list  of  known  suffixes  is  cleared.  There  are  no  commands 
associated  with  .SUFFIXES. 

.MUTEX         Serialize  the  updating  of  specified  targets  (Seethe  Parallel  Make  Section). 


Built-in  Macros 

There  are  five  internally  maintained  macros  that  are  useful  for  writing  rules  for  building  targets.  I  n  order 
to  clearly  define  the  meaning  of  these  macros,  some  clarification  of  the  terms  target  and  dependent  is 
necessary.  When  make  updates  a  target,  it  may  actually  generate  a  series  of  targets  to  update.  Before 
any  rule  (either  explicit  or  implicit)  is  applied  to  the  target  to  update  it,  recursion  takes  place  on  each 
dependent  of  the  target.  The  dependent,  upon  recursion,  becomes  a  target  itself,  and  may  have  or  generate 
its  own  dependents,  which  in  turn  are  recursed  upon  until  a  target  is  found  that  has  no  dependents,  at 
which  point  the  recursion  stops.  Not  all  targets  processed  by  make  appear  as  explicit  targets  in  the 
makefile;  some  of  them  are  explicit  dependents  from  the  makefile  while  others  are  implicit  dependents  gen- 
erated as  make  recursively  updates  the  target.  For  instance,  when  the  following  makefile  is  executed: 

pgm :     a .  o  b .  o 

cc  a .  o  b .  o  -o  pgm 
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the  following  series  of  targets  to  be  made  is  generated: 
 pgm 

with  two  dependents  and  an  explicit  rule  to  follow 

 a.o 

(recursively)  with  an  implicit  dependent  of  a .  c  which  matches  the  implicit  rule  .  c  .o 

 a.c 

(recursively)  with  no  implicit  dependents  and  no  implicit  rules.  This  stops  the  recursion 
and  simply  returns  the  last  modification  time  of  the  file  a.c. 

 b.o 

(recursively)  with  an  implicit  dependent  of  b.  c  which  matches  the  implicit  rule  .  c .  o 

 b.c 

(recursively)  with  no  implicit  dependents  and  no  implicit  rules.  This  stops  the  recursion 
and  merely  returns  the  last  modification  time  of  thefileb.c. 

In  the  definitions  below,  the  word  target  refers  to  a  target  specified  in  the  makefile,  an  explicit  dependent 
specified  in  the  makefile  which  becomes  the  target  when  make  recurses  on  it,  or  an  implicit  dependent 
(generated  as  a  result  of  locating  an  inference  rule  and  file  that  match  the  suffix  of  the  target)  which 
becomes  the  target  when  make  recurses  on  it.  The  word  dependent  refers  to  an  explicit  dependent 
specified  in  the  makefile  for  a  particular  target,  or  an  implicit  dependent  generated  as  a  result  of  locating 
an  appropriate  inference  rule  and  corresponding  file  that  matches  the  suffix  of  the  target. 

It  may  be  helpful  to  think  of  target  rules  as  user  specified  rules  for  a  particular  target  name,  and  inference 
rules  as  user  or  make  specified  rules  for  a  particular  class  of  target  names.  It  may  also  be  helpful  to 
remember  that  the  value  of  the  target  name  and  its  corresponding  dependent  names  change  as  make 
recurses  on  both  explicit  and  implicit  dependents,  and  that  inference  rules  are  only  applied  to  implicit 
dependents  or  to  explicit  dependents  which  do  not  have  target  rules  defined  for  them  in  the  makefile. 

$@  The  $@  macro  is  the  full  target  name  of  the  current  target,  or  the  archive  filename  part  of  a 

library  archive  target.  It  is  evaluated  for  both  target  and  inference  rules. 

$%  The  $%  macro  is  only  evaluated  when  the  current  target  is  an  archive  library  member  of 

the  form  libname  (  member  .  o)  or  libname  ((  entry) ) .  In  these  cases,  $@  evaluates  to 
libname  and  $%  eval  uates  to  member .  o  or  the  object  file  containing  the  symbol  entry. 
$%  is  evaluated  for  both  target  and  inference  rules. 

$?  The$?  macro  is  the  list  of  dependents  that  are  out-of-date  with  respect  to  the  current  tar- 

get; essentially,  those  modules  that  have  been  rebuilt.  It  is  evaluated  for  both  target  and 
inference  rules,  but  is  usually  only  used  in  target  rules.  $?  evaluates  to  one  name  only  in 
an  inference  rule,  but  may  evaluate  to  more  than  one  name  in  a  target  rule. 

$<  I  n  an  inference  rule,  $<  evaluates  to  the  source  file  name  that  corresponds  to  the  implicit 

rulewhich  matches  the  suffix  of  the  target  being  made.  In  other  words,  it  is  the  file  that  is 
out-of-date  with  respect  to  the  target.  I  n  the  .  DEFAULT  rule,  the  $<  macro  evaluates  to 
the  current  target  name.  $<  is  evaluated  only  for  inference  rules.  Thus,  in  the  .c.o  rule, 
the  $<  macro  would  evaluate  to  the  .c  file.  An  example  for  making  optimized  .o  files 
from  .  c  files  is: 

.c.o: 

cc  -c  -O  $*.c 

or: 

.c.o: 

cc  -c  -O  $< 

$*  The  macro  $*  is  the  current  target  name  with  the  suffix  deleted.  It  is  evaluated  only  for 

inference  rules. 

These  five  macros  can  have  alternative  forms.  When  an  uppercase  D  or  F  is  appended  to  any  of  the  five 
macros,  the  meaning  is  changed  to  "directory  part"  for  D  and  "file  part"  for  F.  Thus,  $(@D)  refers  to  the 
directory  part  of  the  string  $@  If  there  is  no  directory  part,  .  /  is  generated.  When  the  $?  macro  con- 
tains more  than  one  dependent  name,  the  $  (?D)  expands  to  a  list  of  directory  name  parts  and  the  $  (?F) 
expands  toa  list  of  the  filename  parts. 

I  n  addition  to  the  built-in  macros  listed  above,  other  commonly  used  macros  are  defined  by  make.  These 
macros  are  used  in  the  default  inference  rules,  and  can  be  displayed  with  the  -p  option.  These  macros  can 
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be  used  in  target  rules  in  the  makefile.  They  can  also  be  redefined  in  the  makefile. 

$$@  The  $$@macro  has  meaning  only  on  dependency  lines.  Macros  of  this  form  are  called 

dynamic  dependencies  because  they  are  evaluated  at  the  time  the  dependency  is 
actually  processed.  $$@  evaluates  to  exactly  the  same  thing  as  $@  does  on  a  com- 
mand line;  i.e.,  the  current  target  name.  This  macro  is  useful  for  building  large 
numbers  of  executable  files,  each  of  which  has  only  one  source  file.  For  instance,  the 
following  HP-UX  commands  could  all  be  built  using  the  same  rule: 

CMDS  =  cat  echo  cmp  chown 
$(CMDS)    :  $$@.c 

$(CC)    -O  $?  -o  $@ 

If  this  makefile  is  invoked  with  make  cat  echo  cmp  chown,  make  builds  each 
target  in  turn  using  the  generic  rule,  with  $$@  eval uati ng  to  cat  while  cat  is  the 
target,  to  echo  when  the  target  is  echo,  and  so  forth. 

The  dynamic  dependency  macro  can  also  take  the  F  form,  $$((3F)  which  represents 
the  filename  part  of  $$@  This  is  useful  if  the  targets  contain  pathnames.  For  exam- 
ple: 

INCDIR  =  /usr/include 
INCLUDES   =   $ (INCDIR) /stdio.h  \ 
$ (INCDIR) /pwd.h  \ 
$ (INCDIR) /dir. h  \ 
$  (INCDIR) /a. out. h 
$  (INCLUDES)     :  $$(@F) 
cp  $?  $@ 
chmod  0444  $@ 

Special  Macros 

TheVPATH  macro  allows  make  to  search  a  colon  separated  list  of  directories  for  dependents.  Lines  of  the 
form  VPATH=  pathl:path2  ...  causes  make  to  first  search  the  current  directory  for  a  dependent  and  if  the 
dependent  is  not  found,  make  searches  pathl  and  continues  until  the  directories  specified  in  the  VPATH 
macro  are  exhausted. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is  unset 
or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  contains  an 
invalid  setting,  make  will  behave  asif  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

PROJECTDIR  provides  a  directory  to  be  used  to  search  for  SCCS  files  not  found  in  the  current  directory. 
I  n  all  of  the  following  cases,  the  search  for  SCCS  files  will  be  made  in  the  directory  SCCS  in  the  identified 
directory.  If  the  value  of  PROJECTDIR  begins  with  a  slash,  it  is  considered  an  absolute  pathname;  other- 
wise, the  home  directory  of  a  user  of  that  name  is  examined  for  a  subdirectory  src  or  source.  If  such  a 
directory  is  found,  it  is  used.  Otherwise,  the  value  is  used  as  a  relative  pathname. 

If  PROJECTDIR  is  not  set  or  has  a  null  value,  the  current  directory  is  searched  first,  followed  by  a  search 
in  the  SCCS  directory  in  the  current  directory. 

The  setting  of  PROJECTDIR  affects  all  files  listed  in  the  remainder  of  this  utility  description  for  files  with 
a  component  named  SCCS. 
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I  nternational  Code  Set  Support 

Singleand  multi-byte  character  code  sets  are  supported. 

RETURN  VALUES 

make  returns  a  0  upon  successful  completion  or  a  value  greater  than  0  if  an  error  occurred.  If  the  -q 
option  is  specified,  make  returns  0  if  the  target  was  up-to-date  and  a  value  greater  than  0  if  the  target  was 
not  up-to-date. 

EXAMPLES 

Thefollowing  example  creates  an  executable  file  from  a  C  source  code  file  without  a  makefile,  if  program. c 
exists  in  the  current  directory: 

make  program 

The  following  example  shows  more  than  one  makefile  specified  and  some  command  line  macros  defined, 
and  updates  the  first  target  in  modulel: 

make  -f  modulel  -f  module2  RELEASE=1 . 0  CFLAGS=-g 

Thefollowing  example  updates  two  targets  in  a  default  makefile  currently  residing  in  the  current  directory: 
make  clobber  prog 

The  following  example  updates  the  prog  target  in  a  specified  makefile,  allows  environment  variables  to 
override  any  common  variables  in  the  makefile,  clears  the  built-in  suffix  list  and  ignore  the  built-in  rules, 
and  outputs  exhaustive  debugging  information: 

make  -erd  -f  modulel  prog 
WARNINGS 

Be  wary  of  any  file  (such  as  an  include  file)  whose  access,  modification,  and  last  change  times  cannot  be 
altered  by  the  make-ing  process.  For  example,  if  a  program  depends  on  an  include  file  that  in  turn 
depends  on  another  include  file,  and  if  one  or  both  of  these  files  are  out-of-date,  make  tries  to  update  these 
files  each  time  it  is  run,  thus  unnecessarily  re-makeing  up-to-date  files  that  are  dependent  on  the  include 
file.  The  solution  is  to  manually  update  these  files  with  the  touch  command  before  running  make  (see 
touch(l)). 

Some  commands  return  non-zero  status  inappropriately;  use-i  to  overcome  the  difficulty. 
File  names  with  the  characters  = :  @$  do  not  work. 

Built-in  commands  that  are  directly  executed  by  the  shell  such  as  cd  (see  cd(l)),  are  ineffectual  across 
new-lines  in  make. 

Thesyntax  (lib(filel.o  file2.o  file3.o)  isillegal. 
You  cannot  build  lib  (file .  o)  from  file  .  o. 
The  macro  $  (a:  .  o=.  c~)  does  not  work. 

Expanded  target  lines  cannot  contain  more  than  16384  characters,  including  the  terminating  new-line. 
If  no  makefile  exists  in  the  current  directory,  typing 

make  filename 
results  in  make  attempting  to  build  filename  from  filename  .  c 

If  make  is  invoked  in  a  shell  script  with  a  quoted  argument  that  evaluates  to  NULL  (such  as  $@),  make 
fails. 

DEPENDENCIES 
NFS  Warning: 

When  comparing  modification  times  of  files  located  on  different  NFS  servers,  make  behaves  unpredictably 
if  the  clocks  on  the  servers  are  not  synchronized. 

FILES 

[Mm]akefile 
s .  [Mm]akef  ile 
SCCS/s.  [Mm]akefile 
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SEE  ALSO 

ccbundled(l),  cd(l),  lex(l),  mkmf(l),  sh(l),  environ(5),  lang(5),  regexp(5). 

A  Nutshell  Handbook,  Managing  Projects  With  Make  by  Steve  Talbot,  Second  Edition,  O'Reilly  &  Associ- 
ates, I  nc,  1986. 

STANDARDS  CONFORMANCE 

make:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  P0SIX.2 
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NAME 

makekey  -  generate  encryption  key 

SYNOPSIS 

/usr/ lbin/ makekey 

DESCRIPTION 

makekey  improves  the  usefulness  of  encryption  schemes  depending  on  a  key  by  increasing  the  amount  of 
time  required  to  search  the  key  space.  It  reads  10  bytes  from  its  standard  input  and  writes  13  bytes  on  its 
standard  output.  The  output  depends  on  the  input  in  a  way  intended  to  be  difficult  to  compute  (i.e.,  to 
requirea  substantial  fraction  of  a  second). 

The  first  eight  input  bytes  (the  input  key)  can  be  arbitrary  ASCII  characters.  The  last  two  (the  salt)  are  best 
chosen  from  the  set  of  digits,  . ,  /,  and  uppercase  and  lowercase  letters.  The  salt  characters  are  repeated 
as  the  first  two  characters  of  the  output.  The  remaining  11  output  characters  are  chosen  from  the  same  set 
as  the  salt  and  constitute  the  output  key. 

The  transformation  performed  is  essentially  the  following:  the  salt  is  used  to  select  one  of  4,096  crypto- 
graphic machines  all  based  on  the  National  Bureau  of  Standards  des  algorithm,  but  broken  in  4,096 
different  ways.  Using  the  input  key  as  key,  a  constant  string  is  fed  into  the  machine  and  recirculated  a 
number  of  times.  The  64  bits  that  come  out  are  distributed  into  the  66  output  key  bits  in  the  result. 

makekey  is  intended  for  programs  that  perform  encryption  (e.g.,  ed(l)  and  crypt(l)).  Usually,  its  input 
and  output  will  be  pipes. 


SEE  ALSO 

crypt(l),  ed(l),  passwd(4). 
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NAME 

man  -  find  manual  information  by  keywords;  print  out  a  manual  entry 

SYNOPSIS 

man  [-M  path]  -k  keyword... 

man  [-M  path]  -f  file... 

man  [-]  [-M  path]  [-T  macro-package]  [section  [subsection  ]]  entryname... 
DESCRIPTION 

man  accesses  information  from  the  HP-UX  manual  pages.  It  can  be  used  to: 

•  List  all  manual  entries  whose  one-line  description  contains  any  of  a  specified  set  of  keywords. 

•  Display  or  print  one-line  descriptions  of  entries  specified  byname. 

•  Search  on-line  manual  directories  by  entry  name  and  display  or  print  the  specified  entry  or  entries. 

•  Search  a  specified  on-line  manual  section  (directory)  and  display  or  print  the  specified  entry  or 
entries  in  that  section. 

Searching  for  Entry  Names  by  Keyword  (first  form) 

The  first  form  above  searches  the  one-line  descriptions  of  individual  entries  for  specified  keywords.  Argu- 
ments are  as  follows: 

-k  keyword  -k  followed  by  one  or  more  keywords  causes  man  to  print  the  one-line  description  of 
each  manual  entry  whose  one-line  description  contains  text  matching  one  or  more  of 
the  specified  keywords  (similar  to  the  behavior  of  grep(l)).  Keywords  are  separated 
by  blanks  (space  or  tab). 

Before  this  option  can  be  used,  file  /usr/share/lib/whatis  must  exist, 
/usr/share/lib/whatis  can  be  created  by  running  catman(lM). 

Obtaining  One-Line  Description  of  an  Entry  (second  form) 

The  second  form  above  finds  and  displays  or  prints  the  one-line  descriptions  of  specified  individual  entries. 
Arguments  are  as  follows: 

-f  file  -f  followed  by  one  or  more  file  names  causes  man  to  print  the  one-line  description  of 

each  manual  entry  found  whose  name  matches  file.  When  specifying  two  or  more 
files,  file  arguments  are  separated  by  blanks  (space  or  tab).  If  entry  names  matching 
file  exist  in  two  or  more  sections,  the  one-line  description  of  each  matched  file  name  is 
output. 

Before  this  option  can  be  used,  file  /usr/share/lib/whatis  must  exist, 
/usr/share/lib/whatis  can  be  created  by  running  catman(lM). 

Viewing  Individual  Manual  Entries  (third  form) 

The  third  form  shown  above  is  used  for  viewing  one  or  more  individual  manual  entries,  man  in  this  form 
recognizes  the  following  arguments: 

(optional)  When  the  -  argument  is  present,  man  sends  the  formatted  manual  entry 
directly  to  standard  output  without  processing  it  through  the  output  filter  specified  by 
the  PAGER  environment  variable. 

-M  path  Change  the  search  path  for  manual  pages,  path  is  a  colon-separated  list  of  directories 

that  contain  manual  page  di rectory  subtrees.  When  used  with  the -k  or  -f  options, 
the  -M  option  must  appear  first. 

-T  macro-package 

man  uses  macro-package  rather  than  the  standard  -man  macros  defined  in 
/usr/share/lib/tmac/tmac .  an  for  formatting  manual  pages. 

When  specifying  the  -T  option  to  man  ,  the  full  path  must  be  given.  For  example: 

man  -T  /usr/share/lib/tmac/tmac . s  Is 

section  [subsection] 

(optional)  Search  in  the  specified  section  for  the  given  entry  name.  section  specifies  a 
single  section  number  or  one  of  the  words  local,  new,  old,  or  public  to  search 
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for  one  or  more  of  the  entries  indicated,  section  corresponds  to  the  section  number 
where  the  entry  appears  in  the  HP-UX  Reference.  It  can  be  followed  by  an  optional 
uppercase/lowercase  subsection  identifier  such  as  3C  which  would  indicate  a  library 
routine  in  Section  3.  3,  3c,  and  3C  are  interpreted  as  equivalent,  since  all  Section  3 
manual  entries  are  stored  in  the  same  or  in  related  directories  (such  as 
/usr/share/man/man3  .  Z  and  /usr  / share/man/ man3 .  However,  if  an 
entry  is  in  Section  1M,  section  must  be  specified  as  lm  or  1M. 

entryname  Search  for  a  specific  entry  name  where  entryname  is  the  name  of  the  manual  entry 
without  its  section-number  suffix.  Except  for  names  exceeding  11  characters, 
entry  name  is  identical  to  the  name  of  the  manual  entry  as  listed  at  the  top  of  each 
page,  or  is  the  same  as  one  of  the  keywords  in  the  left-hand  part  of  the  one-line 
description  in  the  corresponding  manual  entry. 

If  entry  name  is  longer  than  11  characters,  man  first  searches  for  the  full-length 
entry  name.  If  not  found,  entry  name  is  truncated  to  11  characters  to  ensure  that 
there  is  room  for  the  section  suffix  in  14-character  source  file  names.  Files  in  the 
/usr/share/man/*  directories  are  normally  installed  with  the  filename  truncated 
to  11  characters  where  necessary  so  that  the  name  plus  a  three-character  section 
suffix  does  not  exceed  the  maximum  filename  length  on  short  filename  systems. 

If  section  is  not  specified  (see  previous  argument  description),  man  searches  all  sec- 
tions of  the  manual  in  order:  manl,  man2,  manlM,  man3,  man4,  man5,  man6, 
man7,  man8,  man9,  manlocal,  mannew,  manold,  then  manpublic;  and  print- 
ing the  first  matching  entry  it  encounters. 

If  there  is  more  than  one  manual  entry  among  the  sections,  the  first  manual  entry  is 
displayed.  For  example,  man  intro  will  display  only  intro  (1)  .  man  4  intro 
wi  1 1  di  spl  ay  intro  ( 4 )  . 

If  the  standard  output  is  a  teletype,  and  if  the  -  flag  is  not  given,  man  pipes  its  output  through  more 
(see  more(l)),  with  the  -s  option,  to  eliminate  multiple  blank  lines  and  stop  after  each  screenful.  This 
default  behavior  can  be  changed  by  setting  the  PAGER  variable  in  the  user's  environment.  The  value  of 
PAGER  must  be  a  string  that  names  an  output  filter  (such  aspg(l)),  along  with  the  desired  options. 

File  Search  Conventions 

man  searches  in  several  directories,  as  appropriate,  for  the  specified  manual  entry.  The  search  continues 
until  either  the  entry  is  found  or  all  candidate  directories  are  searched.  The  first  three  directories 
searched,  in  order,  are:  /usr/share/man,  /usr/contrib/man,  and  /usr/local/man. 

The  MANPATH  environment  variablecan  be  used  to  specify  directories  to  be  searched,  and,  if  set,  overrides 
the  default  paths  given  above.  Upon  logging  in,  /etc/profile  (  or  /etc/csh .  login  )  sets  the 
MANPATH  environment  variableto  default  settings.  If  the  file  /etc/MANPATH  exists,  the  default  settings 
are  taken  from  this  file.  The  MANPATH  variable  follows  the  same  form  as  the  PATH  variable  (see 
envi  ron(5)). 

Within  each  of  these  directories,  man  searches  in  the  cat*  .  Z  subdirectories,  the  man*  .Z  subdirec- 
tories, the  cat*  subdirectories,  and  the  man*  subdirectories.  man*.Z  and  man*  directories  contain 
nroff(l)-compatible  source  text  for  the  entries,  cat*  .  Z  and  cat*  directories  contain  the  formatted  ver- 
sions of  the  entries,  man*. Zand  cat .  Z  directories  contain  entries  in  compressed  form.  Filesinthese 
directories  are  uncompressed  by  uncompress  (see  compress(l))  before  being  processed  for  printing  or 
display. 

If  the  LANG  environment  variable  is  set  to  any  valid  language  name  defined  by  lang(5),  and  the  MAN- 
PATH  variable  is  not  set,  or  is  set  to  the  default  directories,  man  searches  in  three  additional  directories 
for  the  manual  entry  before  searching  in  /usr/share/man.  First,  man  searches  in 
/usr/share/man/$LANG,  then  in  /usr/contrib/man/$LANG,  then  in 
/usr/local/man/$LANG.  Thus,  native-language  manual  entries  are  displayed  if  they  are  present  and 
installed  properly  in  the  system. 

If  the  MANPATH  environment  variable  is  set  to  anything  other  than  the  default,  the  above  directories  with 
$LANG  as  part  of  the  path  are  not  automatically  searched.  All  directories  must  be  explicitly  given  in 
MANPATH.  The  %L,  %l,  %t,  and  %c  specifiers  can  be  used  as  path  components  to  cause  locale-specific 
directories  to  be  searched.  See  envi  ran (5)  for  a  complete  description  of  MANPATH. 

man  uses  the  most  recent  version  that  it  finds  in  the  subdirectories  searched.  If  the  most  recent  version  is 
in: 


HP-UX  Release  Hi:  December  2000 


-2- 


Section  1-521 


man(l) 


man(l) 


man*.Z  The  entry  is  uncompressed,  formatted,  and  displayed.  If  the  cat*.Z  directory 
exists,  the  formatted  entry  is  compressed  and  installed  in  cat*  .  Z.  If  the  cat* 
directory  exists,  the  formatted  entry  is  installed  in  cat*. 

cat*  .  Z         The  entry  is  uncompressed  and  displayed. 

man*  The  entry  is  formatted,  and  displayed.   If  the  cat*.Z  directory  exists,  it  is 

compressed,  and  installed  in  cat*  .Z.  If  the  cat*  directory  exists,  the  formatted 
entry  is  installed  in  cat*. 

cat*  The  entry  is  displayed. 

If  only  the  cat*  or  cat*  .  Z  subdirectory  is  present  and/or  nroff(l)  is  not  installed,  only  entries  that  are 
already  formatted  can  be  displayed. 

If  you  choose  to  have  the  formatted  entries  on  your  system,  run  catman(lM)  with  the  default,  which 
creates  the  cat*  .  Z  directories  (after  removing  any  cat*  directories  that  exist  on  your  system)  and  also 
creates  the  file  /usr/share/lib/whatis  used  by  the  man  -k  option.  If  you  choose  to  have  the 
cat*  directories,  it  would  be  space-saving  to  remove  any  cat*  .  Z  directories  that  may  exist  on  your  sys- 
tem. Beware  that  man  updates  both  directories  (cat*  and  cat*  .  Z)  if  they  both  exist. 

Special  Manual  Entries 

Some  situations  may  require  creation  of  manual  entries  for  local  use  or  distribution  by  third-party  software 
suppliers.  The  manual  formatting  macros  have  been  structured  to  redefine  page  footers  so  that  manual 
entries  not  originating  from  Hewlett-Packard  Company  do  not  show  the  HP  name  in  the  footer.  For  more 
information  about  this  change  and  a  description  of  the  manual  formatting  macros  used  with  nroff  or 
troff ,  see  man(5). 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  language  in  which  messages  are  displayed.  LANG  is  also  used  to  determine  the 
search  path  (as  described  above). 

If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG 
for  messages,  but  not  for  the  search  path. 

If  any  internationalization  variable  contains  an  invalid  setting,  man  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

MANPATH,  if  set,  gives  a  list  of  directories  to  be  searched  for  the  given  entry,  replacing  the  default  paths. 
PAGER,  if  set,  defines  an  output  filter  to  be  used  instead  of  more(l)  to  paginate  output. 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

EXAMPLES 

List  the  manual  entries  that  contain  the  word  grep  in  their  respective  one-line  description  (name)  lines: 

man  -k  grep 
The  output  is: 

grep,   egrep,    fgrep   (1)   -  search  a  file  for  a  pattern 
zgrep(l)  -  search  possibly  compressed  files  for  a 

regular  expression 

Print  the  one-line  description  of  thegrep(l)  manual  entry: 

man  -f  grep 
Print  the  entire  grep(l)  manual  entry: 

man  grep 

Set  a  search  path  that  includes  a  path  directly  below  the  current  directory.  The  manual  entry,  mypage  is 
assumed  to  exist  in  the  directory  ./manl  (or  .  /manl .  Z,  catl,  or  catl .  Z). 

MANPATH= . : /usr/ share/man : /usr/contrib/man : /usr/local/man 
export  MANPATH 
man  mypage 
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Display  the  manual  entry  for  id(l),  with  the  output  piped  through  pg  -c: 

PAGER="pg  -c" 
export  PAGER 
man  id 

List  all  printed  manuals  availablefor  the  current  system  (see  manuals(5): 

man  manuals 
Display  intro(4)  and  intro(3): 

man  4  Intro 

man  3  intro 

WARNINGS 

Manual  entries  are  structured  such  that  they  can  be  printed  on  a  phototypesetter,  conventional  line 
printer,  and  screen  display  devices.  However,  due  to  line  printer  and  display  device  limitations,  some  infor- 
mation may  be  lost  in  certain  situations. 

FILES 

/usr/share/lib/whatis  keyword  database 

/usr/share/man/cat*  [.Z]/*  formatted  manual  entries  [compressed] 

/usr/share/man/man*  [ .  Z] / *  raw  (nroff(l)  source)  manual  entries  [compressed] 

/usr/contrib/man/cat* [ . Z] /* 
/usr/contrib/man/man* [ . Z] /* 
/usr/local/man/cat* [ . Z]  /* 
/ usr/ local/man/man* [ . Z] / * 

/usr/share/man/$LANG/cat*  [.Z]/*  formatted  native-language  manual  entries  [compressed] 
/usr/share/man/$LANG/man*  [ .  Z]  /  *       raw  (nroff(l)  source)  native-language  manual  entries 

[compressed] 

/usr/contrib/man/$LANG/cat* [ . Z]  /* 
/usr/contrib/man/$LANG/man* [ . Z] / * 
/usr/local/man/$LANG/cat* [.Z]/* 
/usr/local/man/$LANG/man* [ . Z] / * 

SEE  ALSO 

col(l),  compress(l),  grep(l),  more(l),  catman(lM),  fixman(lM),  environ(5),  intro(l),  intro(lM),  intro(2), 
intro(3),  intro(4),  intro(5),  intro(7),  intro(9),  introduction(9),  man(5),  manuals(5). 

STANDARDS  CONFORMANCE 

man:  XPG4 
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NAME 

mediainit  -  initialize  disk  or  partition  dds  tape 
SYNOPSIS 

mediainit  [-vr]  [-f  fmt  optn  ]  [-i  interleave]  [-p  size]  pathname 
DESCRIPTION 

mediainit  initializes  mass  storage  media  by  formatting  the  media,  writing  and  reading  test  patterns  to 
verify  media  integrity,  then  sparing  any  defective  blocks  found.  This  process  prepares  the  disk  or  tape  for 
error-free  operation.  I  nitialization  destroys  all  existing  user  data  in  the  area  being  initialized. 

mediainit  can  also  used  for  partitioning  dds  tape  media.  Seethe  -p  option  below  for  further  details. 
Options 

The  following  command  options  are  recognized.  They  can  be  specified  in  any  order,  but  all  must  precede 
the  pathname.  Options  without  parameters  can  be  listed  individually  or  grouped  together.  Options  with 
parameters  must  be  listed  individually,  but  white  space  between  the  option  and  its  parameter  is  discretion- 
ary. 

-v  Normally,  mediainit  provides  only  fatal  error  messages  which  are  directed  to 

standard  error.  The  -v  (verbose)  option  sends  device-specific  information  related  to 
low-level  operation  of  mediainit  to  standard  output  (stdout).  This  option  is  most 
useful  to  trained  service  personnel  because  it  usually  requires  detailed  knowledge  of 
device  operation  before  the  information  can  be  interpreted  correctly. 

-r  (re-certify)  This  option  forces  a  complete  tape  certification  whether  or  not  the  tape  has 

been  certified  previously.  All  record  of  any  previously  spared  blocks  is  discarded,  so 
any  bad  blocks  will  have  to  be  rediscovered.  This  option  should  be  used  only  if: 

•  It  is  suspected  that  numerous  blocks  on  the  tape  have  been  spared  which 
should  not  have  been,  or 

•  It  is  necessary  to  destroy  (overwrite)  all  previous  data  on  the  tape. 

-f  fmt  optn  The  format  option  is  a  device-specific  number  in  the  range  0  through  239.  It  is 
intended  solely  for  use  with  certain  SS/80  devices  that  support  multiple  media  formats 
(independent  from  interleave  factor).  For  example,  certain  microfloppy  drives  support 
256-,  512-,  and  1024-byte  sectors,  mediainit  passes  any  supplied  format  option 
directly  through  to  the  device.  Thedevicethen  either  accepts  the  format  option  if  it  is 
supported,  or  rejects  it  if  it  is  not  supported.  Refer  to  device  operating  manuals  for 
additional  information.  The  default  format  option  isO. 

-i  interleave  The  interleave  factor,  interleave,  refers  to  the  relationship  between  sequential  logical 
records  and  sequential  physical  records.  It  defines  the  number  of  physical  records  on 
the  media  that  lie  between  the  beginning  points  of  two  consecutively  numbered  logical 
records.  The  choice  of  interleave  factor  can  have  a  substantial  impact  on  disk  perfor- 
mance. 

-p  size  Partition  dds  cartridge  media  into  two  logical  separate  volumes:  partition  0  and  par- 

tition 1: 

•  size  specifies  the  minimum  size  of  partition  1  (in  Mbytes).  The  maximum 
allowed  value  is  1200. 

•  Partition  0  is  the  remainder  of  the  tape  (partition  0  physically  follows  parti- 
tion 1  on  the  tape). 

The  actual  size  of  partition  1  is  somewhat  larger  than  the  requested  size  to  allow  for 
tape  media  errors  during  writing.  Thus,  a  size  of  400  formats  the  dds  tape  into  two 
partitions  where  partition  1  holds  at  least  400  Megabytes  of  data,  and  the  remainder 
of  the  tape  is  used  for  partition  0  (for  a  1300  Mbyte  dds  cartridge,  this  means  that 
partition  0  has  a  size  somewhat  less  than  900  Mbytes). 

Note  that  it  is  unnecessary  to  format  a  dds  tape  before  use  unless  the  tape  is  being 
partitioned.  Unformatted  dds  media  does  not  require  initialization  when  used  as  a 
single  partition  tape.  Accessing  partition  1  on  a  single-partition  tape  produces  an 
error.  To  change  a  two-partition  tape  to  single-partition,  use  mediainit  with  0 
specified  as  the  size. 
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pathname  pathname  is  the  path  name  to  the  character  (raw)  device  special  file  associated  with 
the  device  unit  or  volume  that  is  to  be  initialized,  mediainit  aborts  if  you  lack 
either  read  or  write  permission  to  the  device  special  file,  or  if  the  device  is  currently 
open  for  any  other  process.  This  prevents  accidental  initialization  of  the  root  device  or 
any  mounted  volume,  mediainit  locks  the  unit  or  volume  being  initialized  so  that 
no  other  processes  can  access  it. 

Except  for  SCSI  devices,  pathname  must  be  a  device  special  file  whose  minor  number 
of  the  device  being  initialized  has  the  diagnostic  bit  set.  For  device  special  files  with 
the  diagnostic  bit  set,  the  section  number  is  meaningless.  The  entire  device  is 
accessed. 

When  a  given  unit  contains  multiple  volumes  as  defined  by  the  drive  controller,  any  available  unit  or 
volume  associated  with  that  controller  can  be  initialized,  independent  of  other  units  and  volumes  that  share 
the  same  controller.  Thus,  you  can  initialize  one  unit  or  volume  to  any  format  or  interleave  factor  without 
affecting  formats  or  data  on  companion  units  or  volumes.  However,  be  aware  that  the  entire  unit  or 
volume  (as  defined  by  the  drive  controller)  is  initialized  without  considering  the  possibility  that  it  may  be 
subdivided  into  smaller  structures  by  the  the  operating  software.  When  such  structures  exist,  unexpected 
loss  of  data  is  possible. 

mediainit  dominates  controller  resources  and  limits  access  by  competing  processes  to  other  units  or 
volumes  sharing  the  same  controller.  If  other  simultaneous  processes  need  access  to  the  same  controller, 
some  access  degradation  can  be  expected  until  initialization  is  complete;  especially  if  you  are  initializing  a 
tape  cartridge  in  a  drive  that  shares  the  root  disk  controller. 

In  general,  mediainit  attempts  to  carefully  check  any  -f  (format  option)  or  -i  (interleave  options) 
supplied,  and  aborts  if  an  option  is  out  of  range  or  inappropriate  for  the  media  being  initialized.  Specifying 
an  interleave  factor  or  format  option  value  of  0  has  the  same  effect  as  not  specifying  the  option  at  all. 

For  disks  that  support  interleave  factors,  the  acceptable  range  is  usually  1  (no  interleave)  through  n-1, 
where  n  is  the  number  of  sectors  per  track.  Refer  to  the  appropriate  device  operating  manual  for  recom- 
mended values. 

If  a  disk  being  initialized  requires  an  interleave  factor  but  none  is  specified,  mediainit  provides  an 
appropriate,  though  not  necessarily  optimum  default. 

When  a  given  device  supports  format  options,  the  allowable  range  of  interleave  factors  may  be  related  to 
the  specified  format  option.  In  such  instances,  mediainit  cannot  check  the  interleave  factor  if  one  is 
specified. 

Notes 

Most  types  of  mass  storage  media  must  be  initialized  before  they  can  be  used,  hp  hard  disks,  flexible  disks, 
and  cartridge  tapes  require  some  form  of  initialization,  but  9-track  tapes  do  not.  Initialization  usually 
involves  formatting  the  media,  writing  and  reading  test  patterns,  then  sparing  any  defective  blocks. 
Depending  upon  the  media  and  device  type,  none,  some,  or  all  of  the  initialization  process  may  have  been 
performed  at  the  factory,  mediainit  completes  whatever  steps  are  appropriate  to  prepare  the  media 
for  error-free  operation. 

Most  hp  hard  disks  are  formatted  and  exhaustively  tested  at  the  factory  by  use  of  a  process  more  thorough 
but  also  more  time-consuming  than  appropriate  for  mediainit .  However,  mediainit  is  still  valuable 
for  ensuring  the  integrity  of  the  media  after  factory  shipment,  formatting  with  the  correct  interleave  factor, 
and  sparing  any  blocks  which  may  have  become  defective  si  nee  original  factory  testing  was  performed. 

hp  flexible  disks  are  not  usually  formatted  prior  to  shipment,  so  they  must  undergo  the  entire  initialization 
process  before  they  can  be  used. 

When  a  tape  is  certified,  it  is  thoroughly  tested  and  defective  blocks  are  spared,  mediainit  usually 
certifies  a  tape  only  if  it  has  not  been  certified  previously.  If  the  tape  has  been  previously  certified  and 
spared,  mediainit  usually  reorganizes  the  tape's  spare  block  table,  retaining  any  previous  spares,  and 
optimizing  their  assignment  for  maximum  performance  under  sequential  access.  Reorganizing  the  spare 
block  table  takes  only  a  few  seconds,  whereas  complete  certification  takes  about  a  half-hour  for  150-foot 
tapes,  and  over  an  hour  for  600-foot  tapes. 

Reorganization  of  a  tape's  spare  block  tabletechnically  renders  any  existing  data  undefined,  but  the  data  is 
not  usually  destroyed  by  overwriting.  To  ensure  that  old  tape  data  is  destroyed,  which  is  useful  for  secu- 
rity, complete  tape  re-certification  can  be  forced  with  the  -r  option. 
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Some  applications  may  require  that  a  file  system  be  placed  on  the  media  before  use.  mediainit  does 
not  create  a  file  system;  it  only  prepares  media  for  writing  and  reading.  If  such  a  file  system  is  required, 
other  utilities  such  as  newfs,  lifinit,  or  mkfs  must  be  invoked  after  running  mediainit  (see 
newfs(lM),  lifinit(l),  and  mkfs(lM)). 

RETURN  VALUE 

mediainit  returns  one  of  the  following  values: 

0  Successful  completion. 

1  A  device-related  error  occurred. 

2  A  syntax-related  error  was  encountered. 

ERRORS 

Appropriate  error  messages  are  printed  on  standard  error  during  execution  of  mediainit . 
WARNINGS 

For  a  device  that  contains  multiple  units  on  a  single  controller,  each  unit  can  be  initialized  independently 
from  any  other  unit.  It  should  be  noted,  however,  that  mediainit  requires  that  there  be  no  other 
processes  accessing  the  device  before  initialization  begins,  regardless  of  which  unit  is  being  initialized.  If 
there  are  accesses  currently  in  progress,  mediainit  aborts. 

Aborting  mediainit  is  likely  to  leave  the  medium  in  a  corrupt  state,  even  if  it  was  previously  initialized. 
To  recover,  the  initialization  must  be  restarted. 

During  the  initialization  process,  open  ()  rejects  all  other  accesses  to  the  device  being  initialized,  produc- 
ing the  error  eacces  (see  open (2)). 

DEPENDENCIES 

Series  800 

Partitioning  of  dds  tape  media  (-p  option)  is  not  supported. 

AUTHOR 

mediainit  was  developed  by  HP. 

SEE  ALSO 

lifinit(l),  mkfs(lM),  newfs(lM). 
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NAME 

merge  -  three-way  file  merge 

SYNOPSIS 

merge  [-p]  filel  file2  file3 

DESCRIPTION 

merge  combines  two  files  that  are  revisions  of  a  single  original  file.  The  original  file  is  file2,  and  the 
revised  files  are  filel  and  file3.  merge  identifies  all  changes  that  lead  from  file2  to  file3  and  from  file2  to 
filel,  then  deposits  the  merged  text  into  filel.  If  the  -p  option  is  used,  the  result  goes  to  standard  output 
instead  of  filel. 

An  overlap  occurs  if  both  filel  and  file3  have  changes  in  the  same  place,  merge  prints  how  many  over- 
laps occurred,  and  includes  both  alternatives  in  the  result.  The  alternatives  are  delimited  as  follows: 

«««<  filel 
lines  in  filel 


lines  in  file3 
>»»»  file3 

If  there  are  overlaps,  edit  the  result  in  filel  and  delete  one  of  the  alternatives. 

This  command  is  particularly  useful  for  revision  control,  especially  if  filel  and  file3  are  the  ends  of  two 
branches  that  havefile2  as  a  common  ancestor. 

EXAMPLES 

Atypical  use  for  merge  isas  follows: 

1.  To  merge  an  RCS  branch  into  the  trunk,  first  check  out  the  three  different  versions  from  RCS  (see 
co(l))  and  rename  them  for  their  revision  numbers:  5.2,  5.11,  and  5.2.3.3.  File  5.2.3.3  is  the  end 
of  an  RCS  branch  that  split  off  the  trunk  at  file  5.2. 

2.  For  this  example,  assume  file  5.11  is  the  latest  version  on  the  trunk,  and  is  also  a  revision  of  the 
"original"  file,  5.2.  Merge  the  branch  into  the  trunk  with  the  command: 

merge  5.11  5.2  5.2.3.3 

3.  File  5.11  now  contains  all  changes  made  on  the  branch  and  the  trunk,  and  has  markings  in  the 
file  to  show  all  overlapping  changes. 

4.  Edit  file  5.11  to  correct  the  overlaps,  then  use  the  ci  command  to  check  the  file  back  in  (see 
ci(D). 

WARNINGS 

merge  uses  the  ed(l)  system  editor.  Therefore,  the  file  size  limits  of  ed(l)  apply  tomerge. 
AUTHOR 

merge  was  developed  by  Walter  F.  Tichy. 

SEE  ALSO 

diff3(l),  diff(l),  rcsmerge(l),  co(l). 
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NAME 

mesg  -  permit  or  deny  messages  to  terminal 

SYNOPSIS 

mesg  [[-]  g]  [[-]  y]  [[-]  n] 
mesg 

DESCRIPTION 

The  command  form  mesg  [-]  n  forbids  messages  via  write  by  revoking  write  permission  to  users 
without  appropriate  privilege  on  the  user's  terminal  (see  write(l)).  The  command  form  mesg  [-]  g  rein- 
states permission  so  that  only  legitimate  commands  (such  as  write(l))  can  be  used  by  other  users  to  send 
messages,  mesg  [-]  y  allows  applications  such  as  write  or  talk  to  send  messages  to  the  user's  terminal 
(that  is,  without  restrictions),  mesg  without  any  other  argument  reports  the  current  state  without 
changing  it. 

RETURN  VALUE 

mesg  returns  the  foil  owing  values: 

0  Messages  are  receivable. 

1  Messages  are  not  receivable. 

2  An  error  occurred. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_ME S SAGE S  determines  the  language  i n  which  messages  are  displayed. 

If  LC_ME S SAGE S  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is 
used  as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty 
string,  a  default  of  "C"  (see  lang(5))  is  used  instead  of  LANG. 

If  any  internationalization  variable  contains  an  invalid  setting,  mesg  behaves  as  if  all  internationalization 
variables  are  set  to  "C".  See  envi  ron  (5). 

FILES 

/dev/tty* 

SEE  ALSO 

write(l). 

STANDARDS  CONFORMANCE 

mesg:  SVI D2,  SVI D3,  XPG2,  XPG3,  XPG4 
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NAME 

mkdir  -  make  a  directory 

SYNOPSIS 

mkdir  [-p]  [-m  mode]  dirname  ... 

DESCRIPTION 

mkdir  creates  specified  directories  in  mode  0777  (possibly  altered  by  umask  unless  specified  otherwise  by 
a -m  mode  option  (see  umask(l)).  Standard  entries,  .  (for  the  directory  itself)  and  ..  (for  its  parent)  are 
created  automatically.  If  dirname  already  exists,  mkdir  exits  with  a  diagnostic  message,  and  the  direc- 
tory is  not  changed. 

Options 

mkdir  recognizes  the  following  command-line  options: 

-m  mode  After  creating  the  directory  as  specified,  the  file  permissions  are  set  to  mode,  which  is  a 
symbolic  mode  string  as  defined  for  chmod  (see  chmod(l)).  The  umask(l)  has  pre- 
cedence over  -m. 

-p  I  ntermediate  directories  are  created  as  necessary.  Otherwise,  the  full  path  prefix  of  dir- 

name must  already  exist,    mkdir  requires  write  permission  in  the  parent  directory. 

For  each  directory  name  in  the  pathname  prefix  of  the  dirname  argument  that  is  not  the 
name  of  an  existing  directory,  the  specified  directory  is  created  using  the  current  umask 
setting,  except  that  the  equivalent  of  chmod  u+wx  is  done  on  each  component  to 
ensure  that  mkdir  can  create  lower  directories  regardless  of  the  setting  of  umask. 
Each  directory  name  in  the  pathname  prefix  of  the  dirname  argument  that  matches  an 
existing  directory  is  ignored  without  error.  If  an  intermediate  path  component  exists, 
but  has  permissions  set  to  prevent  writing  or  searching,  mkdir  fails  with  an  error  mes- 
sage. 

If  the  -m  option  is  used,  the  directory  specified  by  dirname  (excluding  directories  in  the 
pathname  prefix)  is  created  with  the  permissions  specified  by  mode. 

Only  LINK_MAX  subdirectories  can  be  created  (see  limits(5)). 

Access  Control  Lists  -  J  FS  File  Systems  Only 

If  the  parent  directory  has  an  access  control  list  (ACL,  see  aclv(5)),  and  that  ACL  contains  default  entries, 
an  ACL  is  created  for  the  new  directory,  and  the  parent  directory's  default  entries  are  applied  to  the  new 
directory's  ACL,  both  as  regular  entries  and  as  default  entries. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If  LANG  is 
unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  internationalization  variables  con- 
tains an  invalid  setting,  mkdir  will  behave  as  if  all  internationalization  variables  are  set  to  "C".  See 
envi  ron(5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization  vari- 
ables. 

LC_CTYPE  determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the  classification 
of  characters  as  printable,  and  the  characters  matched  by  character  class  expressions  in  regular  expres- 
sions. 

LC_ME S SAGE S  determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH  determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

DIAGNOSTICS 

mkdir  returns  exit  code  0  if  all  directories  were  created  successfully.  Otherwise,  it  prints  a  diagnostic  and 
returns  non-zero. 
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mkdir  returns  exit  code  0  if  the  -p  option  was  specified,  and  all  the  specified  directories  now  exist.  If  any 
of  the  intermediate  directories  do  not  have  search  or  write  permission  (with  the  -p  option),  mkdir  prints 
a  diagnostic  and  returns  non-zero. 

EXAMPLES 

Create  directory  gem  beneath  existing  directory  raw  in  the  current  directory: 
mkdir  raw/gem 

Create  directory  path  raw/gem/diamond  underneath  the  current  directory  and  set  permissions  on 
directory  diamond  to  read-only  for  all  users  (a=r): 

mkdir  -p  -m  "a=r"   raw/ gem/ diamond 

which  is  equivalent  to  (see  chmod(l)): 

mkdir  -p  -m  444  raw/ gem/ diamond 

If  directories  raw  or  raw  and  gem  already  exist,  only  the  missing  directories  in  the  specified  path  are 
created. 

SEE  ALSO 

rm(l),  setacl(l),  sh(l),  umask(l),  aclv(5). 

STANDARDS  CONFORMANCE 

mkdir:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  POSIX.2 
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NAME 

mkfifo-  makeFiFO  (named  pipe)  special  files 

SYNOPSIS 

mkfifo  [-p]  [-m  mode]  filename  ... 

DESCRIPTION 

mkfifo  creates  the  FIFO  special  files  named  by  its  operand  list.  The  operands  are  taken  sequentially  in 
the  order  specified  and,  if  the  user  has  write  permission  in  the  appropriate  directory,  the  FIFO  is  created 
with  permissions  0666  modified  by  the  user's  file  mode  creation  mask  (see  umask(2)). 

The  specific  actions  performed  are  equivalent  to  calling 

mkfifo  (filename,  0666) 

for  each  filename  in  the  operand  list  (see  mkfifo(2)). 

Options 

mkfifo  recognizes  the  following  command-line  options: 

-m  mode  After  creating  the  FIFO  special  file,  set  the  permission  bits  of  the  new  file  to  the 
specified  mode  value.  The  mode  option  argument  is  a  symbolic  mode  string  as  defined 
in  chmod(l). 

(XPG4  0nly.)  In  the  symbolic  mode  strings,  the  operators  +  and  -  will  be  interpreted 
relative  to  an  initial  mode  of  a=rw. 

-p  Create  any  missing  intermediate  path  name  components. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LANG  determines  the  locale  to  use  for  the  locale  categories  when  both  LC_ALL  and  the  corresponding 
environment  variable  (beginning  with  LC_)  do  not  specify  a  locale.  If  LANG  is  not  specified  or  is  set  to  the 
empty  string,  a  default  of  "C"  (see  lang(5))  is  used. 

LC_ALL  determines  thelocaleto  use  to  override  any  values  for  locale  categories  specified  by  the  setti  ngs  of 
LANG  or  any  environment  variables  beginning  with  LC_. 

LC_CTYPE  determines  the  locale  for  the  interpretation  of  sequences  of  bytes  of  text  data  as  characters 
(e.g.,  single-  versus  multi byte  characters  in  arguments). 

If  any  internationalization  variable  contains  an  invalid  setting,  mkfifo  behaves  as  if  all  internationaliza- 
tion variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Si  ngle-byte  character  code  sets  are  supported. 

RETURN  VALUE 

mkfifo  returns  zero  if  invoked  with  at  least  one  operand  and  if  all  FIFO  special  files  were  created  success- 
fully. Otherwise,  it  printsa  diagnostic  message  and  returns  non-zero. 

EXAMPLES 

The  foil  owing  command  creates  a  FIFO  special  file  named  peacepipe  in  the  current  directory: 
mkfifo  peacepipe 

SEE  ALSO 

chmod(l),  umask(l),  mknod(lM),  mkfifo(3C). 

STANDARDS  CONFORMANCE 

mkfifo:  XPG3,  XPG4,  POSIX.2 
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NAME 

mkmf  -  make  a  makefile 

SYNOPSIS 

mkmf  [-acdeil  ]  [-f  makefile]  [-F  template]  [-M  language]  [macroname^/alue  ...] 
DESCRIPTION 

The  mkmf  command  creates  a  makefile  that  informs  the  make  command  how  to  construct  and  maintain 
programs  and  libraries  (see  make(l)).  After  gathering  up  all  source  code  file  names  in  the  current  working 
directory  and  inserting  them  into  the  makefile,  mkmf  scans  source  code  files  for  included  files  and  gen- 
erates dependency  information  that  is  appended  to  the  makefile.  Source  code  files  are  identified  by  their 
file  name  suffixes,  mkmf  recognizes  the  following  suffixes: 


c 

C 

C 

C++ 

f 

Fortran 

h 

Include  files 

i 

Pascal  include  files 

1 

Lex  or  Lisp 

o 

Object  files 

P 

Pascal 

r 

Ratfor 

s 

Assembler 

Y 

Yacc 

Themkmf  command  checks  for  an  existing  makefile  before  creating  one.  If  no  -f  option  is  present,  mkmf 
tries  the  makefiles  makefile  and  Makefile,  respectively. 

After  the  makefile  has  been  created,  arbitrary  changes  can  be  made  using  a  text  editor,  mkmf  can  also  be 
used  to  re-edit  the  macro  definitions  in  the  makefile,  regardless  of  changes  that  may  have  been  made  since 
it  was  created. 

By  default,  mkmf  creates  a  program  makefile.  To  create  a  makefile  that  handles  libraries,  the  -1  option 
must  be  used. 

Make  Requests 

Given  a  makefile  created  by  mkmf ,  make  recognizes  the  following  requests: 
all  Compile  and  load  a  program  or  library, 

clean       Remove  all  object  and  core  files, 
clobber    Remove  all  files  that  can  be  regenerated, 
depend     Update  included  file  dependencies  in  a  makefile, 
echo         List  the  names  of  the  source  code  files  on  standard  output. 

extract    Extract  all  object  files  from  the  library  and  place  them  in  the  same  directory  as  the 
source  code  files.  The  library  is  not  altered. 

index       Print  an  index  of  functions  on  standard  output. 

install    Compile  and  load  the  program  or  library  and  move  it  to  its  destination  directory, 
print       Print  source  code  files  on  standard  output. 

tags         Create  a  tags  file  for  the  ex  editor  (see  ex(l)  and  ctags(l)),  for  C,  Pascal,  and  Fortran 
source  code  files. 

update      Recompile  only  if  there  are  source  code  files  that  are  newer  than  the  program  or  library, 
link  and  install  the  program  or  library. 

Several  requests  can  be  given  simultaneously.  For  example,  to  (1)  compile  and  link  a  program,  (2)  move 
the  program  to  its  destination  directory,  and  (3)  remove  any  unnecessary  object  files,  use: 

make  install  clean 

Macro  Definitions 

mkmf  understands  the  foil  owing  macro  definitions: 
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CFLAGS  C  compiler  flags.  After  searching  for  included  files  in  the  directory  currently  being 
processed,  mkmf  searches  in  directories  named  in  -I  compiler  options  and  then  in  the 
/usr /include  directory. 

COMPILESYSTYPE 

Location  of  /usr/include .  If  the  COMPILESYSTYPE  macro  or  environment 
variable  is  defined,  mkmf  searches  for  included  files  in 
/$COMPILESYSTYPE/usr/include  instead  of  /usr/include. 

C++ compiler  flags.  After  searching  for  included  files  in  the  directory  currently  being 
processed,  mkmf  searches  in  directories  named  in  -I  compiler  options  and  then  in  the 
/usr/include/CC  directory,  followed  by  the  /usr/include  directory. 

Directory  where  the  program  or  library  is  to  be  installed. 

List  of  included  files  external  to  the  current  directory,  mkmf  automatically  updates 
this  macro  definition  in  the  makefile  if  dependency  information  is  being  generated. 

Fortran  compiler  flags.  After  searching  for  included  files  in  the  directory  currently 
being  processed,  mkmf  searches  in  directories  named  in  -I  compiler  options,  then  in 
the /usr/include  directory. 

List  of  included  files  in  the  current  directory,  mkmf  automatically  updates  this  macro 
definition  in  the  makefile. 

Installation  program  name. 

Link  editor  name. 

Link  editor  flags. 

Library  name.  Thismacroalsoimpliesthe-1  option. 
List  of  libraries  needed  by  the  link  editor  to  resolve  external  references. 
Makefile  name. 

List  of  object  files,  mkmf  automatically  updates  this  macro  definition  in  the  makefile. 
Program  name. 

List  of  source  code  files,  mkmf  automatically  updates  this  macro  definition  in  the 
makefile. 

List  of  additional  file  name  suffixes  for  mkmf  to  know  about. 

List  of  included  files  found  in  the  /usr/include  directory  hierarchy,  mkmf 
automatically  updates  this  macro  definition  in  the  makefile  if  dependency  information 
is  being  generated.  If  SYSHDRS  is  omitted  from  the  makefile,  mkmf  does  not  gen- 
erate /usr/include  dependencies. 

Both  these  and  any  other  macro  definitions  already  within  the  makefile  can  be  replaced  by  definitions  on 
the  command  line  in  the  form  macroname=value.  For  example,  to  change  the  C  compiler  flags  and  the  pro- 
gram name,  type  the  foil  owing  line: 

mkmf   "CFLAGS=-I . . /include  -O"  PROGRAM=mkmf 

Note  that  macro  definitions  such  as  CFLAGS  with  blanks  in  them  must  be  enclosed  in  double  quote  (") 
marks. 

Environment 

The  environment  is  read  by  mkmf.  All  variables  are  assumed  to  be  macro  definitions  with  the  exception  of 
HDRS,  EXTHDRS,  SRCS,  and  OBJS.  Environment  variables  are  processed  after  command  line  macro 
definitions  and  the  macro  definitions  in  a  makefile.  The  -e  option  forces  the  environment  to  override  the 
macro  definitions  in  a  makefile. 

File  Name  Suffixes 

mkmf  can  recognize  additional  file  name  suffixes,  or  ignore  ones  that  it  already  recognizes,  by  specifying 
suffix  descriptions  in  the  SUFFIX  macro  definition.  Each  suffix  description  takes  the  form  . suffix : tl 
where  t  is  a  character  indicating  the  contents  of  the  file  ( s  =  source  file,  o  =  object  file,  h  =  header  file,  x  = 
executable  file)  and  I  isan  optional  character  indicating  the  include  syntax  for  header  files  (C  =C  syntax, 
C++  =C  syntax  plus  the  addition  of  /usr/include/CC  as  a  standard  search  directory,  F  =  Fortran  and 


CXXFLAGS 

DEST 
EXTHDRS 

FFLAGS 

HDRS 

INSTALL 
LD 

LDFLAGS 
LIBRARY 
LIBS 

MAKEFILE 
OBJS 
PROGRAM 
SRCS 

SUFFIX 
SYSHDRS 


HP-UX  Release  Hi:  December  2000 


-2- 


Section  1-533 


mkmf(l) 


mkmf(l) 


Ratfor  syntax,  P  =Pascal  syntax).  Thefollowing  list  shows  the  default  configuration  for  mkmf : 

.c:sC  C 

.C:sC++  C++ 

.f:sF  Fortran 

.h:h  I  ncludefiles 

.i:h  Pascal  include  files 

.  1 :  sC  Lex  or  Lisp 

.0:0  Objectfiles 

.  p :  sP  Pascal 

.  r :  sF  Ratfor 

.s:s  Assembler 

.  y :  sC  Yacc 

For  example,  to  change  the  object  file  suffix  to  .  obj,  undefine  the  Pascal  include  file  suffix,  and  prevent 
Fortran  files  from  being  scanned  for  included  files,  the  SUFFIX  macro  definition  could  be: 

SUFFIX  =   .  obj : o    . i :    . f : s 


I  nclude  Statement  Syntax 

Thesyntax  of  include  statements  for  C,  C++,  Fortran,  and  Pascal  source  code  are  of  the  form: 

C/C++: 

#include  "filename" 
#include  filename 

where  #  must  be  the  first  character  in  the  line. 

Fortran: 

$include  '  filename  '$ 
$INCLUDE  '  filename  '$ 

where  $  must  be  the  first  character  in  the  line.  Alternatively,  the  $  can  be  omitted  if  the 
include  statement  starts  in  column  7.  I  n  either  case  the  trailing  $  can  be  omitted. 

Pascal: 

$include  '  filename  '$ 
$INCLUDE  '  filename  '$ 

where  $  must  be  the  first  character  in  the  line  and  the  trailing  $  is  optional. 


User-defined  Templates 

If  mkmf  cannot  find  a  makefile  within  the  current  directory,  it  normally  uses  one  of  the  standard  makefile 
templates,  C.p  or  C.l,  in  /usr/ccs/lib/mf  unless  the  user  has  alternative  C.p  or  C.l  template 
files  in  a  directory  $PROJECT/lib/mf  where  $PROJECT  is  the  absolute  path  name  of  the  directory 
assigned  to  the  PROJECT  environment  variable. 


Options 

mkmf  recognizes  thefollowing  options: 


-a  I  nclude  source  files  beginning  with  a  .  in  the  makefile, 

-c  Suppress  "creating  makefile  from  ..."  message. 

-d  Turn  off  scanning  of  source  code  for  include  files.  Old  dependency  information  is 

left  untouched  in  the  makefile. 

-e  Environment  variables  override  macro  definitions  within  makefiles. 

-f  makefile    Specify  an  alternative  makefilefile  name.  The  default  file  name  is  Makefile. 

-i  Prompt  the  user  for  the  name  of  the  program  or  library  and  the  directory  where  it  is 

to  be  installed.  If  a  carriage-return  is  typed  in  response  to  each  of  these  queries, 
mkmf  assumes  that  the  default  program  name  is  a .  out  or  the  default  library  name 
is  lib .  a,  and  the  destination  directory  is  the  current  directory. 

-1  Force  the  makefileto  bea  library  makefile. 
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-F  template  Specify  an  alternative  makefile  template  path  name.  The  path  name  can  be  relative 
or  absolute. 

-M  language  Specify  an  alternative  language-specific  makefile  template.  The  default  language  is  C 
and  the  corresponding  program  and  library  makefile  templates  are  C.p  and  C.l, 
respectively,  mkmf  looks  for  these  templates  in  /usr/ccs/lib/mf  or 
$PROJECT/lib/mf . 


DIAGNOSTICS 

Exit  status  0  is  normal.  Exit  status  1  indicates  an  error. 


WARNINGS 

The  name  of  the  makefile  is  included  as  a  macro  definition  within  the  makefile  and  must  be  changed  if  the 
makefile  is  renamed. 

Since  executable  files  are  dependent  on  libraries,  standard  library  abbreviations  must  be  expanded  to  full 
path  names  within  the  LIBS  macro  definition  in  the  makefile. 

Generated  dependency  information  appears  after  a  line  in  the  makefile  beginning  with  ###.  This  line  must 
not  be  removed,  nor  must  any  other  information  be  inserted  in  the  makefile  below  this  line. 

The  name  of  a  program  or  library  must  not  conflict  with  any  predefined  target  names  in  a  makefile.  It  is 
especially  important  to  avoid  the  the  name  update  to  prevent  make  from  recursively  executing  itself  an 
infinite  number  of  times. 


AUTHOR 

mkmf  was  developed  by  the  University  of  California,  Berkeley. 


FILES 

/usr/ccs/lib/mf /C .p 
/usr/ccs/lib/mf /C . 1 
$PROJECT/lib/mf /C . p 
$PROJECT/lib/mf /C . 1 


Standard  program  makefile  template 
Standard  library  makefile  template 
User-defined  program  makefile  template 
User-defined  library  makefile  template 


SEE  ALSO 

ar(l),  ctags(l),  ld(l),  make(l). 

"Automatic  Generation  of  Make  Dependencies",  Software-Practice  and  Experience,  Walden,  K.,  vol.  14,  no. 
6,  pp.  575-585,  J  une  1984. 
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NAME 

mkmsgs  -  create  message  files  for  use  by  gettxtQ 

SYNOPSIS 

mkmsgs  [-o]  [-i  locale]  textfile  msgfile 

DESCRIPTION 

Themkmsgs  command  takes  as  input  a  file  of  localized  text  strings  and  generates  a  message  file  that  can 
be  accessed  by  the  gettxt(3C)  routine,  textfile  is  the  name  of  the  file  that  contains  the  text  strings,  msgfile 
is  the  name  of  the  output  message  file,  mkmsgs  appends  the  suffix  .  cat  to  the  message  file  name.  The 
combined  length  of  the  file  name  should  be  less  than  14  bytes  for  short  file  name  file  system.  The  msgfile 
fileshould  not  contain  a  colon  sinceit  will  confuse  the  formatting  routines. 

The  textfile  file  contains  the  localized  text  strings.  The  text  strings  are  separated  by  a  newline  character. 
The  text  strings  are  processed  sequentially  and  copied  to  the  msgfile  message  file.  An  empty  line  in  the 
input  results  in  a  corresponding  empty  message  written  to  the  msgfile  message  file. 

Options 

Themkmsgs  command  supports  the  foil  owing  options: 

-o  Overwrite  the  msgfile  message  file  if  it  exists. 

-i  locale  The  msgfile  message  file  is  installed  in  the  system-wide  localization  directory 
corresponding  to  the  specified  locale.  Only  a  user  with  the  appropriate  privileges  can 
create  or  overwrite  the  message  file  in  that  directory.  The  directory  will  be  created  if 
it  does  not  exist. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  messages  as  single-  and/or  multi byte  characters. 

Messages  are  issued  in  LANG  if  it  is  set  to  a  valid  language  and  LANG  messages  are  available.  Otherwise 
"C"  locale  messages  are  issued. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used  as 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setti  ng,  mkmsgs  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi  byte  character  code  sets  are  supported. 

EXAMPLES 

The  foil  owing  example  shows  the  format  of  the  input  text  strings: 

global  %s  not  found\n 

\n\n<press   return  to  continue>\n\n 

\t%s,    %d,   %d,typ  =  %d,   disp  =  '%s'\n 

WARNINGS 

mkmsgs  is  provided  for  SVID3  compatibility  only.  The  user  is  encouraged  to  use  the  NLS  mechanism 
developed  by  HP  and  theX/Open  Company,  Ltd. 

SEE  ALSO 

gencat(l),  gettxt(3C),  setlocale(3C). 

STANDARDS  COMPLIANCE 

mkmsgs :  SVI D3 
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NAME 

mkstr  -  extract  error  messages  from  C  source  i  nto  a  file 

SYNOPSIS 

mkstr  [-]  messagefile  prefix  file  ... 

DESCRIPTION 

mkstr  examines  a  C  program  and  creates  a  file  containing  error  message  strings  used  by  the  program. 
Programs  with  many  error  diagnostics  can  be  made  much  smaller  by  referring  to  places  in  the  file,  and 
reduce  system  overhead  in  running  the  program. 

mkstr  processes  each  of  the  specified  files,  placing  a  revised  version  of  each  in  a  file  whose  name  consists 
of  the  specified  prefix  concatenated  in  front  of  the  original  name.  Atypical  usage  of  mkstr  would  be 

mkstr  mystrings  xx  * . c 

This  command  would  cause  all  the  error  messages  from  the  C  source  files  in  the  current  directory  to  be 
placed  in  the  file  mystrings  and  revised  copies  of  the  source  for  these  files  to  be  placed  in  files  whose  names 
are  prefixed  with  xx. 

When  processing  the  error  messages  in  the  source  for  transfer  to  the  messagefile,  mkstr  searches  for  the 
string  error  (  in  the  input  file.  Each  time  it  is  encountered,  the  C  string  starting  after  the  leading  quote 
is  placed  in  the  messagefile,  followed  by  a  null  character  and  a  new-line  character.  The  null  character  ter- 
minates the  message  so  that  it  can  be  easily  used  when  retrieved,  and  the  new-line  character  makes  it  pos- 
sibleto  conveniently  list  the  error  messagefile  (using  cat,  more,  etc.  —  see  cat(l)  and  more(l))  to  review 
its  contents. 

The  modified  copy  of  the  input  file  is  identical  to  the  original,  except  that  each  occurrence  of  any  string  that 
was  moved  to  the  error  messagefile  is  replaced  by  an  offset  pointer  usable  by  lseek  to  retrieve  the  mes- 
sage. 

If  the  command  line  includes  the  optional  -,  extracted  error  messages  are  placed  at  the  end  of  the  specified 
message  file  (append)  instead  of  overwriting  it.  This  enables  you  to  process  individual  files  that  are  part  of 
larger  programs  that  have  been  previously  processed  by  mkstr  without  reprocessing  all  the  files. 

All  functions  used  by  the  original  program  whose  names  end  in  "error"  that  also  can  take  a  constant  string 
as  their  first  argument  should  be  rewritten  so  that  they  search  for  the  string  in  the  error  messagefile. 

For  example,  a  program  based  on  the  previous  example  usage  would  resemble  the  following: 

#include  <stdio . h> 
#include  <sys/types . h> 
#include  <f cntl . h> 

char  errfile[]    =  "mystrings"  ; 

error  (of  f  set,    a2,   a3,  a4) 
int  offset,    al,   a2,  a3; 
{ 

char  msg [256]  ; 
static  int  fd  =  -1; 

if   (fd  <  0)  { 

fd  =  open(errfile,   0_RDONLY)  ; 

if  (fd  <  0)  { 
perror (errf ile) ; 
exit (1) ; 

} 

} 

if   (lseek  (fd,    (off_t)    offset,    0)    |  |   read(fd,   msg,   256)   <=  0)  { 
printf("?  Can't  find  error  message  in  %s:\n",    errfile)  ; 
perror (errf ile) ; 
exit (1) ; 

} 

printf(msg,    al,    a2,    a3)  ; 

} 
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EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  comments  and  string  literals  as  single-  and/or  multi-byte  char- 
acters. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used 
as  a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  "C"  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  mkstr  behaves  as  if  all  internationalization  variables  are  set  to  "C".  See  environ  (5). 

I  nternational  Code  Set  Support 

Single-  and  multi -byte  character  code  sets  are  supported  within  file  names,  comments,  and  string  literals. 

SEE  ALSO 

lseek(2),  perror(3C),  xstr(l). 

BUGS 

Strings  in  calls  to  functions  whose  names  end  in  error,  notably  perror  ()  ,  may  be  replaced  with  offsets 
by  mkstr. 

Calls  to  error  functions  whose  first  argument  is  not  a  string  constant  are  left  unmodified  without  warning. 
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NAME 

mktemp  -  make  a  name  for  a  temporary  file 
SYNOPSIS 

mktemp  [-c]  [-d  directoryname]  [-p  prefix] 
DESCRIPTION 

mktemp  makes  a  name  that  is  suitablefor  use  as  the  pathname  of  a  temporary  file,  and  writes  that  name 
to  the  standard  output.  The  name  is  chosen  such  that  it  does  not  duplicate  the  name  of  an  existing  file.  If 
the  -c  option  is  specified,  a  zero-length  file  is  created  with  the  generated  name. 

The  name  generated  by  mktemp  is  the  concatenation  of  a  directory  name,  a  slash  ( /  ),  the  value  of  the 
logname  environment  variable  truncated  to  { NAME_MAX }  -  6  characters,  and  the  process  id  of  the 
invoking  process. 

Thedi  rectory  nameischosen  as  follows: 

1.  If  the  -d  option  is  specified,  directory  nameis  used. 

2.  Otherwise,  if  the  TMPDIR  environment  variable  is  set  and  a  string  that  would  yield  a  unique 
name  can  be  obtained  by  using  the  value  of  that  variable  as  a  directory  name,  this  value  is  used. 

3.  Otherwise,  if  a  string  that  would  yield  a  unique  name  can  be  obtained  using  /tmp  as  the  direc- 
tory, /tmp  is  used. 

4.  Otherwise,  .  (current  directory)  is  used. 

If  the  -p  option  is  specified,  prefix  is  used  instead  of  the  value  of  the  LOGNAME  environment  variablefor 
name  generation. 

RETURN  VALUE 

mktemp  returns  zero  on  successful  completion  and  non-zero  if  syntax,  file  access,  or  file  creation  errors 
were  encountered  or  a  unique  pathname  could  not  be  generated. 

SEE  ALSO 

mktemp(3C),  umask(l). 
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NAME 

mm,  osdd  -  print  documents  formatted  with  the  mm  macros 

SYNOPSIS 

mm  [options]  [files] 

osdd  [options]  [files] 
DESCRIPTION 

mm  can  be  used  to  format  and  print  documents  using  nrof  f  and  the  mm  text-formatting  macro  package 
(see  nroff(l)).  It  has  options  to  specify  preprocessing  by  tbl  and/or  neqn,  (see  tbl(l)  and  neqn(l)),  and 
postprocessing  by  various  terminal -oriented  output  filters.  The  proper  pipelines  and  the  required  argu- 
ments and  flags  for  nrof  f  and  mm  are  generated,  depending  on  the  options  selected. 

osdd  is  equivalent  to  the  command  mm  -mosd. 
Options 

mm  recognizes  the  following  options  and  command-line  arguments.  Any  other  arguments  or  options  (such 
as  -rC3)  are  passed  to  nroff  or  to  mm,  as  appropriate.  Such  options  can  occur  in  any  order,  but  they 
must  appear  before  the  files  arguments.  If  no  arguments  are  given,  mm  prints  a  list  of  its  options. 

-Tterm  Specifies  the  type  of  output  terminal;  for  a  list  of  recognized  values  for  term,  type  help 
term2.  If  this  option  is  not  used,  mm  uses  the  value  of  the  shell  variable  $TERM  from  the 
environment  (see  profile(4)  and  environ(5))  as  the  value  of  term  if  $TERM  is  set;  otherwise, 
mm  uses  450  as  the  value  of  term.  If  several  terminal  types  are  specified,  the  last  one  is 
used. 

-12  I  ndicates  that  the  document  is  to  be  produced  in  12-pitch.  Can  be  used  when  $TERM  is  set 
to  one  of  300,  300s,  450,  and  1620.  (The  pitch  switch  on  the  dasi  300  and  300s  termi- 
nals must  be  manually  set  to  12  if  this  option  is  used.) 

-c  Causes  mm  to  invoke  col  (1);  note  that  col  (1)  is  invoked  automatically  by  mm  unless  term  is 
one  of  300,  300s,  450,  37,  4000a,  382,  4014,  tek,  1620,  and  X. 

-e         Causes  mm  to  invoke  neqn. 

-t         Causes  mm  to  invoke  tbl. 

-E         I  nvokes  the  -e  option  of  nroff. 

DIAGNOSTICS 

mm  sends  the  message  mm:  no  input  file  if  none  of  the  arguments  is  a  readablefile  and  mm  i  s  not 
used  as  a  filter. 

EXAMPLES 

Assuming  that  the  shell  variable  $TERM  is  set  in  the  environment  to  450,  the  two  command  lines  below 
are  equivalent: 

mm  -t  -rC3  -12  ghh* 

tbl  ghh*    |   nroff  -cm  -T450-12  -h  -rC3 

mm  reads  the  standard  input  when  -  is  specified  instead  of  any  file  names  (mentioning  other  files  along 
with  -  leads  to  disaster).  This  option  allows  mm  to  be  used  as  a  filter,  as  in  this  example: 

cat  dws    |   mm  - 

Hints 

•  mm  invokes  nroff  with  the  -h  option.  With  this  option,  nroff  assumes  that  the  terminal  has  tabs 
set  every  8  character  positions. 

•  Use  the  -olist  option  of  nroff  to  specify  ranges  of  pages  to  be  output.  Note,  however,  that  mm,  if 
invoked  with  one  or  more  of  the  -e,  -t,  and  -  options,  together  with  the  -olist  option  of  nroff  may 
cause  a  harmless  "broken  pipe"  diagnostic  if  the  last  page  of  the  document  is  not  specified  in  list. 

•  Ifyouusethe  -s  option  of  nroff  (to  stop  between  pages  of  output),  use  line-feed  (rather  than  return 
or  new-line)  to  restart  the  output.  The  -s  option  of  nroff  does  not  work  with  the  -c  option  of  mm, 
or  if  mm  automatically  invokes  col  (see  -c  option  above  and  col  (1)). 


Section  1-540 


-1- 


HP-UX  Release  Hi:  December  2000 


mm(l) 


mm(l) 


•  If  you  specify  an  incorrect  output  terminal  type,  mm  produces  (often  subtle)  unpredictable  results.  How- 
ever, if  you  are  redirecting  output  into  a  file,  use  the  -T37  option,  then  use  the  appropriate  terminal 
filter  when  actually  printing  the  formatted  file. 

SEE  ALSO 

col(l),  env(l),  nroff(l),  tbl(l),  profile(4),  term(4),  mm(5). 
mm  section  in  Text  Formatting:  User's  Guide. 
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NAME 

model  -  print  hardware  model  information 

SYNOPSIS 

model 

DESCRIPTION 

model  prints  the  machine  hardware  model.  Two  or  more  fields  may  be  displayed:  computer,  model 
number,  and  sometimes  the  clock  or  an  additional  model  number. 

Its  output  is  similar  to  that  of  uname  -m.  However,  it  is  recommended  that  the  model  command  or  the 
getconf  command  be  used  to  obtain  the  model  name  since  future  model  names  may  not  be  compatible 
with  uname. 

EXAMPLES 

Here  are  examples  of  what  the  model  command  displays. 
Themodel  output  below  indicates  an  HP  9000  Model  715  with  a  50  MHz  clock. 
9000/715/50 

Themodel  output  below  indicates  an  HP  9000 879  K -CI ass  model  K260. 

9000/879/K260 
Themodel  output  below  indicates  an  HP  9000  871  D-Class  model  D370. 

9000/871/D370 
Themodel  output  below  indicates  an  HP  9000  Model  720. 

9000/720 

SEE  ALSO 

getconf(l),  uname(l). 
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NAME 

more,  page  -  file  perusal  filter  for  crt  viewing 
SYNOPSIS 

more  [-n]  [-cdef isuvz ]  [-n  number]  [-p  command]  [-t  tagstring]  [-x  tabs]  [-W  option] 
[+linenumber]  [+/pattern]  [name  ...] 

page  [-n]  [-cdefisuvz]  [-n  number]  [-p  command]  [-t  tagstring]  [-x  tabs]  [-W  option] 
[+linenumber ]  [+/pattern]  [name  ...] 

REMARKS: 

pg  is  preferred  in  some  standards  and  has  some  added  functionality,  but  does  not  support  character 
highlighting  (see  pg(l)). 

DESCRIPTION 

more  is  a  filter  for  examining  continuous  text,  one  screenful  at  a  time,  on  a  soft-copy  terminal.  It  is  quite 
similar  to  pg,  and  is  retained  primarily  for  backward  compatibility,  more  normally  pauses  after  each 
screenful,  printing  the  filename  at  the  bottom  of  the  screen.  To  display  one  more  line,  press  <Return>. 
To  display  another  screenful  press  <Space>.  Other  possibilities  are  described  later. 

more  and  page  differ  only  slightly,  more  scrolls  the  screen  upward  as  it  prints  the  next  page,  page 
clears  the  screen  and  prints  a  new  screenful  of  text  when  it  prints  a  new  page.  Both  provide  one  line  of 
overlap  between  screenfuls. 

name  can  be  a  filename  or  -,  specifying  standard  input,  more  processes  file  arguments  in  the  order 
given. 

more  supports  the  Basic  Regular  Expression  syntax  (see  regexp(5)). 

more  recognizes  the  following  command  line  options: 

-n  number      Set  the  number  of  lines  in  the  display  window  to  number,  a  positive  decimal  integer. 

The  default  is  one  line  less  than  the  the  number  of  lines  displayed  by  the  terminal;  on 
a  screen  that  displays  24  lines,  the  default  is  23.  The  -n  flag  overrides  any  values 
obtained  from  the  environment. 

-n  Same  as  -n  number  except  that  the  number  of  lines  is  set  to  n. 

-c  Draw  each  page  by  beginning  at  the  top  of  the  screen,  and  erase  each  line  just  before 

drawing  on  it.  This  avoids  scrolling  the  screen,  making  it  easier  to  read  while  more 
iswriting.  Thisoption  is  ignored  if  the  terminal  has  no  clear-to-end-of-line  capability. 

-d  Prompt  user  with  the  message  Press   space  to  continue,    q  to  quit, 

h  for  help  at  the  end  of  each  screenful.  This  is  useful  if  more  is  being  used  as  a 
filter  in  some  setting,  such  as  a  training  class,  where  many  users  might  be  unsophisti- 
cated. 

-e  Exit  immediately  after  writing  the  last  lineof  the  last  file  in  the  argument  list 

-f  Count  logical  lines,  rather  than  screen  lines.  That  is,  long  lines  are  not  folded.  This 

option  is  recommended  if  nroff  output  is  being  piped  through  ul,  si  nee  the  latter  can 
generate  escape  sequences.  These  escape  sequences  contain  characters  that  would 
ordinarily  occupy  screen  positions,  but  which  do  not  print  when  sent  to  the  terminal 
as  part  of  an  escape  sequence.  Thus  more  might  assume  lines  are  longer  than  they 
really  are,  and  fold  lines  erroneously. 

-i  Perform  pattern  matchi  ng  i  n  searches  without  regard  to  case. 

-s  Squeeze  multiple  blank  lines  from  the  output,  producing  only  one  blank  line.  Espe- 

cially helpful  when  viewing  nroff  output,  this  option  maximizes  the  useful  information 
present  on  the  screen. 

-u  Normally,  more  handles  underlining  and  bold  such  as  produced  by  nroff  in  a  manner 

appropriate  to  the  particular  terminal:  if  the  terminal  supports  underlining  or  has  a 
highlighting  (usually  inverse-video)  mode,  more  outputs  appropriate  escape 
sequences  to  enable  underlining,  else  highlighting  mode,  for  underlined  information  in 
the  source  file.  If  the  terminal  supports  highlighting,  more  uses  that  mode  i nforma- 
tion  that  should  be  printed  in  bol dface  type.  The  -u  option  suppresses  this  process- 
ing, as  do  the  "ul"  and  "os"  termi  nfo  flags. 
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-v  Do  not  display  nonprinting  characters  graphically;  by  default,  all  non-ASCII  and  con- 

trol characters  (except  <Tab>,  <Backspace>,  and  <Return>)  are  displayed  visi- 
bly in  the  form  "X  for  <ctrl-x>,  or  M-x  for  non-ASCII  character  x. 

-z  Same  as  not  specifying  -v,  with  the  exception  of  displaying  <Backspace>  as  ~H, 

<Return>  as  ~M,  and  <Tab>  as  "I. 

-p  command  Execute  the  more  command  initially  in  the  command  argument  for  each  file  exam- 
ined. If  the  command  is  a  positioning  command,  such  as  a  line  number  or  a  regular 
expression  search,  sets  the  current  position  to  represent  the  final  results  of  the  com- 
mand, without  writing  any  intermediate  lines  of  the  file.  If  the  positioning  command 
is  unsuccessful,  the  first  linein  the  file  is  the  current  position. 

Write  the  screenful  of  the  file  containing  the  tag  named  by  the  tagstring  argument. 
The  specified  tag  appears  in  the  current  position.  If  both  -p  and  -t  options  are 
specified,  more  processes  -t  first;  that  is,  the  file  containing  the  tagstring  is 
selected  by  -t  and  then  the  command  is  executed. 

Set  the  tabstops  every  tabs  position.  The  default  value  for  the  tabs  argument  is  8. 

Provides  optional  extensions  to  the  more  command.  Currently,  the  following  two 
options  are  supported: 

notite  Prevents  more  from  sending  the  terminal  initialization  string 
before  displaying  the  file.  This  argument  also  prevents  more 
from  sending  the  terminal  de-initialization  string  before  exiting. 

tite  Causes  more  to  send  the  initialization  and  de-initialization 

strings.  This  is  the  default. 

Start  listing  such  that  the  current  position  is  set  to  linenumber. 

Start  listing  such  that  the  current  position  is  set  to  two  lines  above  the  line  matching 
the  regular  expression  pattern. 

Note:  Unlike  editors,  this  construct  should  NOT  end  with  a  /.  If  it  does,  the  trailing 
slash  is  taken  as  character  in  the  search  pattern. 

The  number  of  lines  availableper  screen  is  determined  by  the  -n  option,  if  present  or  by  examining  values 
in  the  environment.  The  actual  number  of  lines  written  is  one  less  than  this  number,  as  the  last  line  of  the 
screen  is  used  to  write  a  user  prompt  and  user  input. 

The  number  of  columns  availableper  line  is  determined  by  examining  values  in  the  environment,  more 
writes  lines  containing  more  characters  than  would  fit  into  this  number  of  columns  by  breaking  the  line  into 
one  more  logical  lines  where  each  of  these  lines  but  the  last  contains  the  number  of  characters  needed  to  fill 
the  columns.  The  logical  lines  are  written  independently  of  each  other;  that  is,  commands  affecting  a  single 
line  affect  them  separately. 

While  determining  the  number  of  lines  and  the  number  of  columns,  if  the  methods  described  above  do  not 
yield  any  number  then  more  uses  terminfo  descriptor  files  (see  term(4)).  If  this  also failsthen  the  number 
of  lines  is  set  to  24  and  the  number  of  columns  to  80. 

When  standard  output  is  a  terminal  and  -u  is  not  specified,  more  treats  backspace  characters  and 
carriage-return  characters  specially. 

•  A  character,  followed  first  by  a  backspace  character,  then  by  an  underscore  (_),  causes  that  charac- 
ter to  be  written  as  underlined  text,  if  the  terminal  supports  that.  An  underscore,  followed  first  by 
a  backspace  character,  then  any  character,  also  causes  that  character  to  be  written  as  underlined 
text,  if  the  terminal  supports  that. 

•  A  backspace  character  that  appears  between  two  identical  printable  characters  causes  the  first  of 
those  two  characters  to  be  written  as  emboldened  text,  if  the  terminal  type  supports  that,  and  the 
second  to  be  discarded.  I  mmediately  subsequent  occurrences  of  backspaces/character  pairs  for  that 
same  character  is  also  discarded. 

•  Other  backspace  character  sequences  is  written  directly  to  the  terminal,  which  generally  causes 
the  character  preceding  the  backspace  character  to  be  suppressed  in  the  display. 

•  A  carriage-return  character  at  the  end  of  a  line  is  ignored,  rather  than  being  written  as  a  control 
character. 


-t  tagstring 


-x  tabs 
-W  option 


+linenumber 
+/ pattern 
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If  the  standard  output  is  not  a  terminal  device,  more  always  exits  when  it  reaches  end-of-file  on  the  last 
file  in  its  argument  list.  Otherwise,  for  all  files  but  the  last,  more  prompts,  with  an  indication  that  it  has 
reached  the  end  of  file,  along  with  the  name  of  the  next  file.  For  the  last  file  specified,  or  for  the  standard 
input  if  no  file  is  specified,  more  prompts,  indicating  end-fo-file,  and  accept  additional  commands.  If  the 
next  command  specifies  forward  scrolling,  more  will  exit.  If  the  -e  option  is  specified,  more  will  exit 
immediately  after  writing  the  last  line  of  thelast  file. 

more  uses  the  environment  variable  more  to  preset  any  flags  desired.  The  MORE  variable  thus  sets  a 
string  containing  flags  and  arguments,  preceded  with  hyphens  and  blank-character-separated  as  on  the 
command  line.  Any  command-line  flags  or  arguments  are  processed  after  those  in  the  MORE  variable,  as  if 
the  command  line  were  as  follows: 

more  $MORE  flags  arguments 
For  example,  to  view  files  using  the  -c  mode  of  operation,  the  shell  command  sequence 

MORE='-c'    ;    export  MORE 
or  the  csh  command 

setenv  MORE  -c 

causes  all  invocations  of  more,  including  invocations  by  programs  such  as  man  and  msgs,  to  use  this  mode. 
The  command  sequence  that  sets  up  the  more  environment  variable  is  usually  placed  in  the  .profile  or 
.cshrc  file. 

In  the  foil  owing  descriptions,  the  current  position  refers  to  two  things: 

•  the  position  of  the  current  lineon  the  screen 

•  the  line  number  (in  the  file)  of  the  current  lineon  the  screen 

The  line  on  the  screen  corresponding  to  the  current  position  is  the  third  line  on  the  screen.  If  this  is  not 
possible  (there  are  fewer  than  three  lines  to  display  or  this  is  the  first  page  of  the  file,  or  it  is  the  last  page 
of  the  file),  then  the  current  position  iseither  the  first  or  last  lineon  the  screen. 

Other  sequences  that  can  be  typed  when  more  pauses,  and  their  effects,  are  as  follows  (i  is  an  optional 
integer  argument,  defaulting  to  1): 

i  <Return> 
i  j 

i<Ctrl-e> 

i<Space>  Scroll  forward  i  lines.  The  default  i  for  <Space>  is  one  screenful;  for  j  and 
<Return>  it  is  one  line.  The  entire  i  lines  are  written,  even  if  i  is  more  than  the 
screen  size.  At  end-of-file,  <Return>  causes  more  to  continue  with  the  next  file  in 
the  list,  or  exits  if  the  current  file  is  the  last  file  in  the  list. 

id 

i<Ctrl-d>  Scroll  forward  i  lines,  with  a  default  of  one  half  of  the  screen  size.  If  i  is  specified,  it 
becomes  the  new  default  for  subsequent  d  and  u  commands. 

iu 

i<Ctrl-u>  Scrolls  backward  i  lines,  with  a  default  of  one  half  of  the  screen  size.  If  i  is  specified,  it 
becomes  the  new  default  for  subsequent  d  and  u  commands. 

ik 

i<Ctrl-y>  Scrolls  backward  i  lines,  with  a  default  of  one  line.  The  entire  i  lines  are  written,  even 
if  i  is  more  than  the  screen  size. 

iz  Display  i  more  lines  and  sets  the  new  window  (screenful)  size  to  i  . 

ig  Go  to  line  i  in  the  file,  with  a  default  of  1  (beginning  of  file).  Scroll  or  rewrite  the 

screen  so  that  the  line  is  at  the  current  position.  If  i  is  not  specified,  then  more 
displays  the  first  screenful  in  the  file. 

iG  Go  to  line  i  in  the  file,  with  a  default  of  the  end  of  the  file.  If  i  is  not  specified,  scrolls 

or  rewrites  screen  so  that  the  last  line  in  the  file  is  at  the  bottom  of  the  screen.  If  i  is 
specified,  scrollsor  rewrites  the  screen  so  that  the  line  is  at  the  current  position. 

is  Skipforwardi  lines,  with  a  default  of  1,  and  write  the  next  screenful  beginning  at  that 

point.  If  i  would  cause  the  current  position  to  be  such  that  less  than  one  screenful 
would  be  written,  the  last  screenful  in  the  file  is  written. 
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if 

i<ctrl-f>     Move  forward  i  lines,  with  a  default  of  one  screenful.  At  end-of-file,  more  will  con- 
tinue with  the  next  file  in  the  list,  or  exit  if  the  current  file  is  the  last  file  in  the  list. 

ib 

i<ctrl-b>     Move  backward  i  lines,  with  a  default  of  one  screenful.  If  i  is  more  than  the  screen 
size,  onlythe  final  screenful  will  be  written. 

q 
Q 
:q 

:Q 
zz 


Exit  from  more. 


<Ctrl-g> 


Write  the  name  of  the  file  currently  being  examined,  the  number  relative  to  the  total 
number  of  files  there  are  to  examine,  the  current  line  number,  the  current  byte 
number,  and  the  total  bytes  to  write  and  what  percentage  of  the  file  precedes  the 
current  position.  All  of  these  items  reference  the  first  byte  of  the  line  after  the  last 
line  written. 

Invoke  an  editor  to  edit  the  current  file  being  examined.  The  name  of  the  editor  is 
taken  from  the  environment  variable  EDITOR,  or  default  to  vi.  If  EDITOR 
represents  either  vi  or  ex,  the  editor  is  invoked  with  options  such  that  the  current 
editor  line  is  the  physical  line  corresponding  to  the  current  position  in  more  at  the 
time  of  the  invocation. 

When  the  editor  exits,  more  resumes  on  the  current  file  by  rewriting  the  screen  with 
the  current  line  as  the  current  position. 

Display  a  description  of  all  the  more  commands. 


i  /[ !  ]expression 


Search  forward  in  the  file  for  the  i-th  line  containing  the  regular  expression  expres- 
sion. The  default  value  for  i  is  1.  The  search  starts  at  the  line  following  the  current 
position.  If  the  search  is  successful,  the  screen  is  modified  so  that  the  searched-for 
line  is  in  the  current  position.  The  null  regular  expression  (/<Return>)  repeats  the 
search  using  the  previous  regular  expression.  If  the  character  !  is  included,  the  lines 
for  searching  are  those  that  do  not  contain  expression. 

If  there  are  less  than  i  occurrences  of  expression,  and  the  input  is  a  file  rather  than  a 
pipe,  then  the  position  in  the  file  remains  unchanged. 

The  user's  erase  and  kill  characters  can  be  used  to  edit  the  regular  expression.  Eras- 
ing back  past  the  first  column  cancels  the  search  command. 


i  ?[ !  ]expression 


!  command 


Same  as  /,  but  searches  backward  in  the  file  for  the  i  th  line  containing  the  regular 
expressi  on  expressi  on . 

Note:  Unlike  editors,  the  ?.  construct  should  NOT  end  with  a  /.  If  it  does,  the  trail- 
ing slash  is  taken  as  a  character  in  the  search  pattern. 

Repeat  the  previous  search  for  the  i-th  line  (default  1)  containing  the  last  expression 
(or  not  containing  the  last  expression,  if  the  previous  search  was  / !  or  ? ! ). 

Repeat  the  search  for  the  opposite  direction  of  the  previous  search  for  the  i-th  line 
(default  1)  containing  the  last  expression 

(2  apostrophes)  Return  to  the  position  from  which  the  last  large  movement  command 
was  executed  ("large  movement"  is  defined  as  any  movement  of  more  than  a  screenful 
of  lines).  If  no  such  movements  have  been  made,  return  to  the  beginning  of  the  file. 

Invoke  a  shell  with  command.  The  characters  %  and  !  in  command  are  replaced 
with  the  current  file  name  and  the  previous  shell  command,  respectively.  If  there  is 
no  current  file  name,  %  is  not  expanded.  The  sequences  \%  and  \!  are  replaced  by 
%  and  !  respectively. 
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:e  [file] 

E  [file]  Examinea  new  file.  If  the  fileargument  is  not  specified,  the  "current"  file  (see  the  :n 

and  :p  commands)  from  the  list  of  files  in  the  command  line  is  re-examined.  The 
filename  is  subjected  to  the  process  of  shell  word  expansions.  If  file  is  a  #  (number 
sign)  character,  the  previously  examined  file  is  re-examined. 

i  :n  Examine  the  next  file.  If  i  is  specified,  examines  the  i-th  next  file  specified  in  the  com- 

mand line. 

i  :p  Examine  the  previous  file.  If  a  number  i  is  specified,  examines  the  i-th  previous  file 

specified  in  the  command  line. 

:t  tagstring    Go  to  the  supplied  tagstring  and  scroll  or  rewrite  the  screen  with  that  line  in  the 
current  position. 

m  letter  Mark  the  current  position  with  the  specified  letter,  where  letter  represents  the  name 

of  one  of  the  lower-case  letters  of  the  portable  character  set. 

'  letter  Return  to  the  position  that  was  previously  marked  with  the  specified  letter,  making 

that  line  the  current  position. 

r 

<Ctrl-l>      Refresh  the  screen. 

R  Refresh  the  screen,  discarding  any  buffered  input. 

Dot.  Repeat  the  previous  command. 

A\  Halt  a  partial  display  of  text,    more  stops  sending  output,  and  displays  the  usual 

prompt.  Unfortunately,  some  output  is  lost  as  a  result. 

The  commands  take  effect  immediately;  i.e.,  it  is  not  necessary  to  press  <Return> .  Up  to  the  time  when 
the  command  character  itself  is  given,  the  line-kill  character  can  be  used  to  cancel  the  numerical  argument 
bei  ng  formed. 

If  the  standard  output  is  not  a  teletype,  more  is  equivalent  to  cat(l). 

more  supports  the  SIGWINCH  signal,  and  redraws  the  screen  in  response  to  window  size  changes. 

EXTERNAL  INFLUENCES 
Environment  Variables 

COLUMNS       Overrides  the  system-selected  horizontal  screen  size. 

EDITOR         Used  by  the  v  command  to  select  an  editor. 

LANG  Provides  a  default  value  for  the  internationalization  variables  that  are  unset  or  null.  If 

LANG  is  unset  or  null,  the  default  value  of  "C"  (see  lang(5))  is  used.  If  any  of  the  interna- 
tionalization variables  contains  an  invalid  setting,  more  will  behave  as  if  all  internationali- 
zation variables  are  set  to  "C".  See  environ  (5). 

LC_ALL  If  set  to  a  non-empty  string  value,  overrides  the  values  of  all  the  other  internationalization 
variables. 

LC_CTYPE  Determines  the  interpretation  of  text  as  single  and/or  multi-byte  characters,  the 
classification  of  characters  as  printable,  and  the  characters  matched  by  character  class 
expressions  in  regular  expressions. 

LC_MES SAGES 

Determines  the  locale  that  should  be  used  to  affect  the  format  and  contents  of  diagnostic 
messages  written  to  standard  error  and  informative  messages  written  to  standard  output. 

NLSPATH       Determines  the  location  of  message  catalogues  for  the  processing  of  LC_ME S SAGE S  . 

LINES  Overrides  the  system-selected  vertical  screen  size,  used  as  the  number  of  lines  in  a  screen- 

ful. The  -n  option  takes  precedence  over  the  LINES  variablefor  determining  the  number 
of  lines  in  a  screenful. 

MORE  Determines  a  string  containing  options,  preceded  with  hyphens  and  blank-character- 

separated  as  on  the  command  line.  Any  command-line  options  are  processed  after  those  in 
the  MORE  variable.  The  MORE  variable  takes  precedence  over  the  TERM  and  LINES 
variables  for  determining  the  number  of  lines  in  a  screenful. 
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TERM  Determines  the  name  of  the  terminal  type. 

I  nternational  Code  Set  Support 

Single-  and  multi-byte  character  code  sets  are  supported. 

APPLICATION  USAGE 

When  the  standard  output  is  not  a  terminal,  none  of  the  filter-modification  options  is  effective.  This  is  based 
on  historical  practice.  For  example,  a  typical  implementation  of  man  pipes  its  output  through  more  -s  to 
squeeze  excess  white  space  for  terminal  users.  When  man  is  piped  to  lp,  however,  it  is  undesirable  for  this 
squeezing  to  happen. 

EXAMPLES 

To  view  a  simplefile,  use: 

more  filename 
To  preview  nroff  output,  use  a  command  resembling: 

nroff  -mm  +2  doc.n    |   more  -s 
If  the  file  contains  tables,  use: 

tbl  file  |  nroff  -mm  |   col   |  more  -s 

Todisplayfile  stuff  in  a  fifteen  line-window  and  convert  multipleadjacent  blank  lines  intoa  singleblank 
line: 

more  -s  -n  15  Stuff 
Toexamineeach  file  with  its  last  screenful: 
more  -p  Gfilelfile2 

To  examine  each  file  starting  with  line  100  in  the  current  position  (third  line,  so  line  98  is  the  first  line  writ- 
ten): 

more  -p  lOOg  filel  fil e2 
To  examine  the  file  that  contains  the  tagstring  tag  with  line  30  in  the  current  position: 
more  -t  tag  -p  30g 

WARNINGS 

Standard  error,  file  descriptor  2,  is  normally  used  for  input  during  interactive  use  and  should  not  be 
redirected  (see  I  nput/Output  section  in  the  manpageof  the  shell  in  use). 

FILES 

/usr/share/lib/terminfo/?/*    compiled  terminal  capability  data  base 
AUTHOR 

more  was  developed  by  Mark  Nudleman,  University  of  California,  Berkeley,  OSF,  and  HP. 
SEE  ALSO 

csh(l),  man(l),  pg(l),  sh(l),  term(4),  terminfo(4),  environ(5),  lang(5),  regexp(5). 

STANDARDS  CONFORMANCE 

more: XPG4 


Section  1-548 


-6- 


HP-UX  Release  Hi:  December  2000 


mpsched(l) 


mpsched(l) 


NAME 

mpsched  -  control  the  processor  or  locality  domain  on  which  a  specific  process  executes 

SYNOPSIS 

mpsched  -h 

mpsched  -s 

mpsched  [-g]  [-P  policy]  [-T  policy]  [-1  locality-domain-id]  [-c  spu]  command 
mpsched  [-qu]  [-P  policy]  [-1  locality-domain-id]  [-c  spu]  {-p  pid}... 

DESCRIPTION 

mpsched  controls  the  processor  (spu),  or  locality  domain  (locality-domain-id)  on  which  a  process  executes. 
It  can  do  this  by  binding  a  process  to  a  particular  processor  or  locality  domain,  or  by  setting  the  launch  pol- 
icy for  the  process. 

The  command  may  be  invoked  in  four  manners. 

•  With -h,  it  prints  a  help  message. 

•  With  -s,  it  returns  the  hardware  configuration  of  the  system.  This  includes  information  about  the 
number  of  locality  domains  and  processors  active  in  the  system. 

•  With  a  command  and  its  arguments,  it  applies  the  binding  or  launch  policy  to  this  command. 

•  With  -p,  it  applies  the  binding  or  launch  policy  to  the  specified  pid. 

Options 

The  command-line  options  are: 

-c  spu 

Bind  the  specified  processes  to  the  spu  listed.  This  will  ensure  that  the  processes  always  run  on  the 
indicated  processor.  This  option  may  be  used  with  the-P,  — T,  and  -p  options. 

-g    Enablegang  scheduling  on  th  No  other  options  may  be  used  with  -g. 

-h    Print  a  help  message. 

-1  locality-domain-id 

Bind  the  specified  processes  to  the  locality-domain  listed.  This  will  ensure  that  the  processes  always 
run  on  the  indicated  domain.  This  option  may  be  used  with  the  -P,  — T,  and  -p  options. 

~P  P'd 

Specify  process  ID,  pid.  To  use  the  pid  option,  the  caller  must  be  a  member  of  a  group  having 
PRIV_MPCTL  access,  besuperuser,  or  have  the  same  effective  user  ID  as  the  pid.  Specifyinga  com- 
mand instead  of  the  -p  option  does  not  require  special  privileges.  Multiple  -p  options  may  be 
specified  per  command  line,  although  each  -p  option  can  takeonly  a  singleprocess  ID. 

-q  Query  the  system  regarding  process  bindings.  This  will  return  information  about  whether  processes 
are  bound  to  a  processor  or  locality  domain.  It  will  also  report  on  the  thread  and  process  launch  poli- 
cies for  the  processes.  If  this  option  is  used  in  conjunction  with  -p  then  only  those  processes  specified 
are  queried.  If  this  option  is  specified  alone,  then  the  status  of  all  processes  on  the  system  that  differ 
from  the  default  settings  are  displayed. 

-s    Print  the  system  hardware  configuration.  No  other  options  may  be  specified. 

-u  Unbind  the  processes  from  any  processor  or  locality  domain  bindings  that  may  be  present.  This  option 
can  be  used  only  with  -p  and  no  other  options  may  be  specified. 

-P  pol  i  cy 

Apply  the  specified  policy  to  the  processes.  Launch  policies  affect  the  locality  domain  on  which  a  pro- 
cess is  spawned.  This  option  may  be  used  with  the  — T,  -p,  -c,  and  -1  options,  policy  is  one  of  the 
following  values. 

RR  Round  robin  launch  policy.  Under  this  policy,  successive  child  processes  are  launched  in  a 

round  robin  fashion  across  the  other  locality  domains  in  the  system  relative  to  creating 
thread. 

LL  Least  loaded  launch  policy.  Under  this  policy,  child  processes  are  launched  on  the  least 

loaded  node  in  the  system  at  the  time  of  creation. 
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FILL  Fill  first  launch  policy.  Under  this  policy,  successive  processed  are  launched  on  the  same 
locality  domain  as  their  parent  until  one  has  been  launched  on  each  processor  in  the  locality 
domain.  At  that  point,  new  processes  are  created  on  the  next  locality  domain. 

PACKED  Packed  launch.  Under  this  policy,  successive  processes  are  launched  on  the  same  locality 
domain  as  their  parent.  A  different  domain  is  never  selected. 

NONE      No  special  policy.  The  default  HP-UX  launch  policy  is  used. 

-T  policy 

Apply  the  specified  policy  to  the  threads  of  the  process.  The  scheduling  policies  are  the  same  as  for 
the  -P  option  except  that  they  apply  to  newly  created  threads  instead  of  processes.  Also,  thread  poli- 
cies may  only  be  specified  on  commands  launched  from  the  command  line  of  mpsched.  The  option 
may  be  used  with  the  -P,  -p,  -1,  and  -c  options. 

Operands 

The  command-line  operands  are: 

command 

A  command  including  its  arguments. 

RETURN  VALUE 

mpsched  returns  exit  status  0  if  command  is  successfully  scheduled  or  -1  if  it  fails. 

EXAMPLES 

Execute  the  a .  out  file  on  processor  2: 

mpsched  -c  2  a . out 

Set  the  process  launch  policy  for  the  existing  process  with  pid  24217  to  round  robin: 

mpsched  -P  RR  -p  24217 
Bind  the  processes  with  pids  1247  and  1842  to  processor  4: 

mpsched  -c  4  -p  1247  -p  1842 

AUTHOR 

mpsched  was  developed  by  HP. 

SEE  ALSO 

getprivgrp(l),  setprivgrp(lM),  fork(2),  getprivgrp(2),  mpctl(2),  privgrp(4). 
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NAME 

mt  -  magnetic  tape  manipulating  program 

SYNOPSIS 

mt  [-f  tapename]  command  [count] 

Obsolescent 

mt  [-t  tapename]  command  [count] 

DESCRIPTION 

mt  is  used  to  give  commands  to  the  tape  drive.  If  tapename  is  not  specified,  the  environment  variable 
TAPE  is  used;  if  TAPE  is  not  defined,  the  default  drive  is  used. 

mt  winds  the  tape  in  the  requested  direction  (forward  or  backward),  stopping  after  the  specified  count  EOF 
marks  or  records  are  passed.  If  count  is  not  specified,  one  is  assumed.  Each  EOF  mark  counts  as  one 
record.  When  winding  backwards,  the  tape  always  stops  at  the  BOT  marker,  regardless  of  the  number 
remaining  in  count. 

mt  accepts  the  foil  owing  commands: 


Spacing  operations  (back  or  forward  space  file  or  record)  leave  the  tape  positioned  past  the  object  being 
spaced  to  in  the  direction  of  motion.  That  is,  backspacing  a  file  leaves  the  the  tape  positioned  before  the  file 
mark,  forward  spacing  a  file  leaves  the  tape  positioned  after  the  file  mark.  This  is  consistent  with  all  classi- 
cal usage  on  tapes. 


Only  raw,  no-rewind  Berkeley-type  devices  should  be  specified.  This  type  of  device  will  not  reposition  the 
tape  upon  close.  An  example  of  such  a  device  is  /dev/rmt/Omnb.  Please  refer  to  mt(7)  for  more  details. 

It  is  possible  to  wind  the  tape  beyond  the  EOT  marker  and  off  the  end  of  the  reel. 

A  reservation  may  only  be  cleared  with  a  release  by  the  host  that  issued  the  original  reserve.  I  n  the  event 
that  the  host  that  holds  the  reservation  is  no  longer  available,  the  st  command  may  be  used  to  reclaim  the 
device  by  issuing  a  bus  device  reset.  Refer  to  st(lM)  for  more  details. 

The  reserve/release  functionality  can  only  be  issued  to  drives  using  the  stape  driver. 
EXAMPLES 

Rewind  the  tape  associated  with  the  device  file  /dev/rmt/Omnb: 
mt  -f  /dev/rmt/Omnb  rew 


eof 


Write  count  EOF  marks. 


f  sf  Forward  space  count  files. 

f  sr  Forward  space  count  records. 

bsf  Backward  space  count  files. 

bsr  Backward  space  count  records. 

rew  Rewind  tape. 

offl  Rewind  tapeand  go  offline. 

eod  Seek  to  end  of  data  (DDS  and  QIC  drives  only). 

smk  Write  count  setmarks  (DDS  drives  only). 

f  ss  Forward  space  count  setmarks  (DDS  drives  only). 

bss  Backward  space  count  setmarks  (DDS  drives  only). 

status  Print  status  information  about  the  tape  drive. 

res  Reserve  tape  drive  for  sole  use  by  the  host  issuingthe  mt  command  (stape  driver  only), 

rel  Release  tape  drive  from  sole  use  by  the  host  issuingthe  mt  command  (stape  driver  only). 


WARNINGS 


FILES 


/dev/rmt/* 


Raw  magnetic  tape  interface 
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/dev/rmt/Omnb   Default  tape  interface 
AUTHOR 

mt  was  developed  by  the  University  of  California,  Berkeley. 

SEE  ALSO 

dd(l),  mt(7),  st(lM). 
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NAME 

mv  -  move  or  rename  files  and  directories 

SYNOPSIS 

mv  [— f  |  — i]  [-e  extarg]  filel  new-file 

mv  [-f  |-i]  [-e  extarg]  filel  [file2  ...]  dest-di rectory 

mv  [-f|-i]  [-e  extarg]  directoryl  [directory2  ...  ]  dest-di  rectory 

DESCRIPTION 

Themv  command  moves: 

•  One  file  (filel)  to  a  new  or  existing  file  (new-file). 

•  One  or  more  files  (filel,  [file2,  ...])  to  an  existing  directory  (dest-di rectory). 

•  One  or  more  directory  subtrees  (directoryl,  [directory2,  ...])  to  a  new  or  existing  directory  (dest- 
di  rectory). 

Moving  filel  to  new-file  is  used  to  rename  a  file  within  a  directory  or  to  relocate  a  file  within  a  file  system  or 
across  different  file  systems.  When  the  destination  is  a  directory,  one  or  more  files  are  moved  into  that 
directory.  If  two  or  more  files  are  moved,  the  destination  must  be  a  directory.  When  moving  a  single  file  to 
a  new  file,  if  new-fileexists,  its  contents  are  destroyed. 

If  the  access  permissions  of  the  destination  dest-di  rectory  or  existing  destination  file  new-file  forbid  writing, 
mv  asks  permission  to  overwrite  the  file.  This  is  done  by  printing  the  mode  (see  chmod(2)  and  Access  Con- 
trol Lists  below),  followed  by  the  first  letters  of  the  words  yes  and  no  in  the  language  of  the  current  locale, 
prompting  for  a  response,  and  reading  one  line  from  the  standard  input.  If  the  response  is  affirmative  and 
the  action  is  permissible,  the  operation  occurs;  if  not,  the  command  proceeds  to  the  next  source  file,  if  any. 

If  filel  is  a  file  and  new-file  is  a  link  to  another  file  with  other  links,  the  other  links  remain  and  new-file 
becomes  a  new  file.  If  filel  is  a  file  with  links  or  a  link  to  a  file,  the  existing  file  or  link  remains  intact,  but 
the  name  is  changed  to  new-file  which  may  or  may  not  be  in  the  directory  where  filel  resided,  depending  on 
directory  path  names  used  in  the  mv  command.  The  last  access  and  modification  times  of  the  file  or  files 
being  moved  remain  unchanged. 

Options 

mv  recognizes  the  following  options: 

-f  Perform  mv  commands  without  prompting  for  permission.  This  option  is  assumed 

when  the  standard  input  is  not  a  terminal. 

-i  Causes  mv  to  write  a  prompt  to  standard  output  before  moving  a  file  that  would 

overwrite  an  existing  file.  If  the  response  from  the  standard  input  is  affirmative,  the 
file  is  moved  if  permissions  allow  the  move. 

-e  extarg       Specifies  the  handling  of  any  extent  attributes  of  the  files(s)  to  be  moved,  extarg  can 
be  one  of  the  fol  I  owi  ng  val  ues: 

warn         Issue  a  warning  message  if  extent  attributes  cannot  be  preserved,  but 
movethefileanyway. 

ignore      Do  not  preserve  extent  attributes. 

force       Do  not  move  the  file  if  the  extent  attributes  cannot  be  preserved. 

If  multiple  source  files  are  specified  with  a  single  target  directory,  mv  will 
move  the  files  that  either  do  not  have  extent  attributes  or  that  have 
extent  attributes  that  can  be  preserved,  mv  will  not  move  the  files  if  it 
cannot  preserve  their  extent  attributes. 

Extent  attributes  cannot  be  preserved  if  the  files  are  being  moved  to  a  file  system  that 
does  not  support  extent  attributes  or  if  that  file  system  has  a  different  block  size  than 
the  original.  If  -e  is  not  specified,  the  default  value  for  extarg  is  warn. 

Access  Control  Lists  (ACLs) 

If  optional  ACL  entries  are  associated  with  new-file,  mv  displays  a  plus  sign  (+)  after  the  access  mode  when 
asking  permission  to  overwrite  the  file. 
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If  new-file  is  a  new  file,  it  inherits  the  access  control  list  of  fil el,  altered  to  reflect  any  difference  in  owner- 
ship between  the  two  files  (see  acl(5)  and  aclv(5)).  In  J  FS  file  systems,  new  files  created  by  mv  do  not 
inherit  their  parent  directory's  default  ACL  entries  (if  any),  but  instead  retain  their  original  ACLs.  When 
moving  files  from  a  J  FS  file  system  to  an  HFS  file  system  or  vice  versa,  optional  ACL  entries  are  lost. 

EXTERNAL  INFLUENCES 
Environment  Variables 

LC_CTYPE  determines  the  interpretation  of  text  as  single  byte  and/or  multi byte  characters. 

LANG  and  LC_CTYPE  determine  the  local  language  equivalent  of  y  (for  yes/no  queries). 
LANG  determines  the  language  in  which  messages  are  displayed. 

If  LC_CTYPE  is  not  specified  in  the  environment  or  is  set  to  the  empty  string,  the  value  of  LANG  is  used  as 
a  default  for  each  unspecified  or  empty  variable.  If  LANG  is  not  specified  or  is  set  to  the  empty  string,  a 
default  of  C  (see  lang(5))  is  used  instead  of  LANG.  If  any  internationalization  variable  contains  an  invalid 
setting,  mv  behaves  as  if  all  internationalization  variables  are  set  to  C.  See  environ  (5). 

I  nternational  Code  Set  Support 

Single  character  and  multi  byte  character  code  sets  are  supported. 

EXAMPLES 

Rename  a  file  in  the  current  directory: 

mv  old-filename  new-filename 

Rename  a  directory  in  the  current  directory: 

mv  old-dirname  new-dirname 

Rename  a  file  in  the  current  directory  whose  name  starts  with  a  nonprinting  control  character  or  a  charac- 
ter that  is  special  to  the  shell,  such  as  -  and  *  (extra  care  may  be  required  depending  on  the  situation): 

mv   . /bad-filename  new-filename 
mv   . /?bad-f ilename  new-filename 
mv   . /*bad-f ilename  new-filename 

Move  directory  sourcedir  and  its  contents  to  a  new  location  (targetdir)  in  the  file  system  (upon 
completion,  a  subdirectory  named  sourcedir  resides  in  directory  targetdir): 

mv  sourcedir  targetdir 

Move  all  files  and  directories  (including  links)  in  the  current  directory  to  a  new  location  underneath  tar- 
getdir : 

mv  *  targetdir 

Move  all  files  and  directories  (including  links)  in  sourcedir  to  a  new  location  underneath  targetdir 
(sourcedir  and  targetdir  are  in  separate  directory  paths): 

mv  sourcedir/*  targetdir 
WARNINGS 

If  filel  and  new-file  exist  on  different  file  systems,  mv  copies  the  file  and  deletes  the  original.  I  n  this  case 
the  mover  becomes  the  owner  and  any  linking  relationship  with  other  files  is  lost,  mv  cannot  carry  hard 
I  inks  across  file  systems.  If  filel  isa  directory,  mv  copies  the  entire  directory  structure  onto  the  destination 
file  system  and  deletes  the  original. 

mv  cannot  be  used  to  perform  the  foil  owing  operations: 

•  Renameeither  thecurrent  working  directory  or  its  parent  directory  usingthe  .  or.,  notation. 

•  Rename  a  directory  to  a  new  name  identical  to  the  name  of  a  file  contained  in  the  same  parent 
directory. 

DEPENDENCIES 
NFS 

Access  control  lists  of  networked  files  are  summarized  (as  returned  in  stmode  by  stat(2)),  but  not  copied  to 
the  new  file.  When  using  mv  on  such  files,  a  +  is  not  printed  after  the  mode  val  ue  when  asking  for  permis- 
sion to  overwrite  a  file. 
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AUTHOR 

mv  was  developed  by  AT&T,  the  University  of  California,  Berkeley  and  HP. 
SEE  ALSO 

cp(l),  cpio(l),  ln(l),  rm(l),  link(lM),  lstat(2),  readlink(2),  stat(2),  symlink(2),  symlink(4),  ad (5),  aclv(5). 

STANDARDS  CONFORMANCE 

mv:  SVID2,  SVID3,  XPG2,  XPG3,  XPG4,  P0SIX.2 
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